nexo-brain 5.3.28 → 5.4.0

package/src/cli.py

@@ -922,6 +922,19 @@ def _update(args):
                 print(f"  Model recommendation check skipped: {exc}", file=sys.stderr)
         else:
             print(f"UPDATE FAILED: {result.get('error', 'sync failed')}", file=sys.stderr)
+
+    # Auto-migrate calibration.json flat → nested once per user. Silent on
+    # no-op; logs a line if an actual migration happened.
+    try:
+        from calibration_migration import detect as _cal_detect, apply_migration as _cal_apply
+        if _cal_detect()["shape"] == "flat":
+            mig = _cal_apply()
+            if mig.get("status") == "migrated" and not args.json:
+                print(f"[NEXO] calibration.json migrated flat → nested (backup: {mig.get('backup')})",
+                      flush=True)
+    except Exception:
+        pass
+
     return 0 if result.get("ok") else 1
 
 
@@ -1295,6 +1308,105 @@ def _chat(args):
     return int(result.returncode)
 
 
+def _notify(args):
+    """Emit an event to the runtime events bus (events.ndjson)."""
+    from events_bus import emit
+    try:
+        event = emit(
+            args.type,
+            text=getattr(args, "text", "") or "",
+            reason=getattr(args, "reason", "") or "",
+            priority=getattr(args, "priority", "normal"),
+            source=getattr(args, "source", "nexo-brain"),
+        )
+    except ValueError as exc:
+        print(json.dumps({"ok": False, "error": str(exc)}), file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps({"ok": True, "event": event}, ensure_ascii=False, indent=2))
+    else:
+        print(f"notify: id={event['id']} type={event['type']} priority={event['priority']}")
+    return 0
+
+
+def _health(args):
+    """Collect a health snapshot and print it."""
+    from health_check import collect
+    report = collect()
+    if getattr(args, "json", True) is False:
+        # minimal text mode
+        print(f"status: {report.get('status', 'unknown')}")
+        for name, sub in report.get("subsystems", {}).items():
+            print(f"  {name:10s} {sub.get('status', '?')}")
+        return 0 if report.get("status") == "ok" else 1
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0 if report.get("status") == "ok" else 1
+
+
+def _logs(args):
+    """Tail recent logs: events bus + operations/*.log."""
+    import glob as _glob
+    lines_want = max(1, int(getattr(args, "lines", 100)))
+    source = (getattr(args, "source", "all") or "all").lower()
+
+    results: dict = {"source": source, "lines": lines_want, "entries": []}
+    home = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+    def _collect_events(n: int) -> list[dict]:
+        try:
+            from events_bus import tail as _tail
+            return _tail(lines=n)
+        except Exception as exc:
+            return [{"error": f"events tail failed: {exc}"}]
+
+    def _collect_ops(n: int) -> list[dict]:
+        ops_dir = home / "operations"
+        if not ops_dir.is_dir():
+            return []
+        files = sorted(
+            ops_dir.glob("*.log"),
+            key=lambda p: p.stat().st_mtime if p.exists() else 0,
+            reverse=True,
+        )[:5]
+        out: list[dict] = []
+        for log in files:
+            try:
+                text = log.read_text(errors="ignore").splitlines()[-n:]
+            except Exception as exc:
+                out.append({"file": str(log), "error": str(exc)})
+                continue
+            for line in text:
+                out.append({"file": log.name, "line": line})
+        return out[-n:]
+
+    if source in ("all", "events"):
+        results["entries"].extend({"kind": "event", **e} for e in _collect_events(lines_want))
+    if source in ("all", "operations"):
+        results["entries"].extend({"kind": "log", **e} for e in _collect_ops(lines_want))
+    if source not in ("all", "events", "operations"):
+        # Treat as filename match inside operations/
+        specific = home / "operations" / source
+        if specific.is_file():
+            try:
+                text = specific.read_text(errors="ignore").splitlines()[-lines_want:]
+                results["entries"] = [{"kind": "log", "file": specific.name, "line": ln} for ln in text]
+            except Exception as exc:
+                results["error"] = str(exc)
+        else:
+            results["error"] = f"unknown log source: {source}"
+
+    if args.json:
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        for entry in results["entries"][-lines_want:]:
+            if entry.get("kind") == "event":
+                print(f"[event] id={entry.get('id')} {entry.get('type')} "
+                      f"{entry.get('priority')} {entry.get('text','')}")
+            else:
+                print(f"[{entry.get('file','?')}] {entry.get('line','')}")
+    return 0
+
+
 def _doctor(args):
     """Run unified doctor diagnostics."""
     try:
@@ -1306,6 +1418,22 @@ def _doctor(args):
         return 1
 
     init_db()
+
+    # Calibration migration hook — runs before the orchestrator so the rest
+    # of doctor sees the canonical nested shape.
+    want_migrate = getattr(args, "migrate_calibration", False) or args.fix
+    dry = getattr(args, "calibration_dry_run", False)
+    if want_migrate or dry:
+        from calibration_migration import detect, apply_migration
+        shape = detect()
+        if shape["shape"] == "flat":
+            mig = apply_migration(dry_run=dry)
+            if args.json:
+                print(json.dumps({"calibration_migration": mig}, ensure_ascii=False, indent=2))
+            else:
+                print(f"[NEXO] calibration migration: {mig.get('status')} — {mig.get('reason','')}",
+                      file=sys.stderr, flush=True)
+
     tier_label = getattr(args, "tier", "boot") or "boot"
     print(f"[NEXO] Inspecting {tier_label} diagnostics... please wait.", file=sys.stderr, flush=True)
     report = run_doctor(tier=args.tier, fix=args.fix, plane=getattr(args, "plane", ""))
@@ -1855,6 +1983,10 @@ def main():
     )
     doctor_parser.add_argument("--json", action="store_true", help="JSON output")
     doctor_parser.add_argument("--fix", action="store_true", help="Apply deterministic fixes")
+    doctor_parser.add_argument("--migrate-calibration", action="store_true",
+                               help="Force calibration.json flat → nested migration")
+    doctor_parser.add_argument("--calibration-dry-run", action="store_true",
+                               help="Preview the calibration migration without writing")
 
     # -- contributor --
     contributor_parser = sub.add_parser("contributor", help="Public Draft PR contribution mode")
@@ -1944,6 +2076,43 @@ def main():
     dashboard_parser = sub.add_parser("dashboard", help="Web dashboard control")
     dashboard_parser.add_argument("action", choices=["on", "off", "status"], help="Start, stop, or check dashboard")
 
+    # -- desktop bridge (read-only, for NEXO Desktop and any external UI) --
+    schema_parser = sub.add_parser("schema", help="Editable-field schema for Preferences UI")
+    schema_parser.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    identity_parser = sub.add_parser("identity", help="Canonical assistant identity")
+    identity_parser.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    onboard_parser = sub.add_parser("onboard", help="Onboarding wizard steps")
+    onboard_parser.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    scan_profile_parser = sub.add_parser("scan-profile", help="Build profile.json from CLAUDE.md + calibration")
+    scan_profile_parser.add_argument("--json", action="store_true", help="JSON output")
+    scan_profile_parser.add_argument("--apply", action="store_true", help="Write profile.json (default is preview)")
+    scan_profile_parser.add_argument("--force", action="store_true", help="Overwrite existing profile.json on --apply")
+
+    # -- runtime events bus + operational observability --
+    notify_parser = sub.add_parser("notify", help="Emit an event to the runtime event bus")
+    notify_parser.add_argument("type", choices=[
+        "attention_required", "proactive_message", "followup_alert",
+        "health_alert", "info",
+    ], help="Event type")
+    notify_parser.add_argument("--text", default="", help="Short user-facing message")
+    notify_parser.add_argument("--reason", default="", help="Internal reason / trigger")
+    notify_parser.add_argument("--priority", choices=["low", "normal", "high", "urgent"], default="normal")
+    notify_parser.add_argument("--source", default="nexo-brain", help="Who emitted this event")
+    notify_parser.add_argument("--json", action="store_true", help="JSON output")
+
+    health_parser = sub.add_parser("health", help="Snapshot of NEXO Brain subsystem health")
+    health_parser.add_argument("--json", action="store_true", help="JSON output (default)")
+
+    logs_parser = sub.add_parser("logs", help="Tail recent operational logs")
+    logs_parser.add_argument("--tail", action="store_true", help="Tail mode (default)")
+    logs_parser.add_argument("--lines", type=int, default=100, help="How many lines to return")
+    logs_parser.add_argument("--source", default="all",
+                             help="Log source: all | events | operations | <logname>")
+    logs_parser.add_argument("--json", action="store_true", help="JSON output")
+
     args = parser.parse_args()
 
     if args.help or (not args.command and not args.version):
@@ -2037,6 +2206,20 @@ def main():
         return _uninstall(args)
     elif args.command == "dashboard":
         return _dashboard(args)
+    elif args.command in ("schema", "identity", "onboard", "scan-profile"):
+        from desktop_bridge import cmd_schema, cmd_identity, cmd_onboard, cmd_scan_profile
+        return {
+            "schema": cmd_schema,
+            "identity": cmd_identity,
+            "onboard": cmd_onboard,
+            "scan-profile": cmd_scan_profile,
+        }[args.command](args)
+    elif args.command == "notify":
+        return _notify(args)
+    elif args.command == "health":
+        return _health(args)
+    elif args.command == "logs":
+        return _logs(args)
     else:
         _print_help()
         return 0

package/src/desktop_bridge.py

@@ -0,0 +1,459 @@
+"""Desktop bridge — read-only commands for NEXO Desktop (Electron UI).
+
+Exposes four read-only commands so Desktop can auto-adapt its UI:
+  nexo schema --json       → editable-field schema for Preferences UI
+  nexo identity --json     → canonical assistant identity + source path
+  nexo onboard --json      → onboarding wizard steps
+  nexo scan-profile        → build profile.json from CLAUDE.md + memory
+
+All commands honor NEXO_HOME. None mutate state unless --apply is passed
+on scan-profile (default is dry-run: prints the proposed payload).
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SCHEMA_VERSION = 1
+ONBOARD_VERSION = 1
+
+
+def _nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+
+
+def _calibration_path() -> Path:
+    return _nexo_home() / "brain" / "calibration.json"
+
+
+def _profile_path() -> Path:
+    return _nexo_home() / "brain" / "profile.json"
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        if path.is_file():
+            return json.loads(path.read_text())
+    except Exception:
+        pass
+    return {}
+
+
+def _print_json(payload: Any) -> int:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    return 0
+
+
+# ------------------------------------------------------------------ schema
+
+def _schema_fields() -> list[dict]:
+    """Canonical list of editable fields across calibration.json / profile.json.
+
+    Each field declares its storage path (dot notation) and which file it
+    lives in, so Desktop can read/write precisely without guessing.
+    """
+    return [
+        {
+            "path": "user.name",
+            "file": "calibration.json",
+            "label": {"es": "Nombre", "en": "Name"},
+            "type": "text",
+            "group": "personal",
+        },
+        {
+            "path": "user.language",
+            "file": "calibration.json",
+            "label": {"es": "Idioma", "en": "Language"},
+            "type": "select",
+            "group": "personal",
+            "options": [
+                {"value": "es", "label": {"es": "Español", "en": "Spanish"}},
+                {"value": "en", "label": {"es": "Inglés", "en": "English"}},
+                {"value": "ca", "label": {"es": "Catalán", "en": "Catalan"}},
+                {"value": "fr", "label": {"es": "Francés", "en": "French"}},
+                {"value": "de", "label": {"es": "Alemán", "en": "German"}},
+                {"value": "it", "label": {"es": "Italiano", "en": "Italian"}},
+                {"value": "pt", "label": {"es": "Portugués", "en": "Portuguese"}},
+            ],
+        },
+        {
+            "path": "user.timezone",
+            "file": "calibration.json",
+            "label": {"es": "Zona horaria", "en": "Timezone"},
+            "type": "text",
+            "group": "personal",
+            "default": "Europe/Madrid",
+        },
+        {
+            "path": "user.assistant_name",
+            "file": "calibration.json",
+            "label": {"es": "Nombre del asistente", "en": "Assistant name"},
+            "type": "text",
+            "group": "personal",
+            "default": "NEXO",
+        },
+        {
+            "path": "personality.autonomy",
+            "file": "calibration.json",
+            "label": {"es": "Autonomía", "en": "Autonomy"},
+            "type": "select",
+            "group": "personality",
+            "options": [
+                {"value": "conservative", "label": {"es": "Conservadora", "en": "Conservative"}},
+                {"value": "balanced", "label": {"es": "Equilibrada", "en": "Balanced"}},
+                {"value": "full", "label": {"es": "Plena", "en": "Full"}},
+            ],
+        },
+        {
+            "path": "personality.communication",
+            "file": "calibration.json",
+            "label": {"es": "Comunicación", "en": "Communication"},
+            "type": "select",
+            "group": "personality",
+            "options": [
+                {"value": "concise", "label": {"es": "Concisa", "en": "Concise"}},
+                {"value": "balanced", "label": {"es": "Equilibrada", "en": "Balanced"}},
+                {"value": "detailed", "label": {"es": "Detallada", "en": "Detailed"}},
+            ],
+        },
+        {
+            "path": "personality.honesty",
+            "file": "calibration.json",
+            "label": {"es": "Honestidad", "en": "Honesty"},
+            "type": "select",
+            "group": "personality",
+            "options": [
+                {"value": "firm-pushback", "label": {"es": "Firme", "en": "Firm pushback"}},
+                {"value": "mention-and-follow", "label": {"es": "Menciona y sigue", "en": "Mention and follow"}},
+                {"value": "just-execute", "label": {"es": "Solo ejecuta", "en": "Just execute"}},
+            ],
+        },
+        {
+            "path": "personality.proactivity",
+            "file": "calibration.json",
+            "label": {"es": "Proactividad", "en": "Proactivity"},
+            "type": "select",
+            "group": "personality",
+            "options": [
+                {"value": "reactive", "label": {"es": "Reactiva", "en": "Reactive"}},
+                {"value": "suggestive", "label": {"es": "Sugerente", "en": "Suggestive"}},
+                {"value": "proactive", "label": {"es": "Proactiva", "en": "Proactive"}},
+            ],
+        },
+        {
+            "path": "personality.error_handling",
+            "file": "calibration.json",
+            "label": {"es": "Errores", "en": "Error handling"},
+            "type": "select",
+            "group": "personality",
+            "options": [
+                {"value": "brief-fix", "label": {"es": "Arreglo breve", "en": "Brief fix"}},
+                {"value": "explain-and-learn", "label": {"es": "Explica y aprende", "en": "Explain and learn"}},
+            ],
+        },
+        {
+            "path": "preferences.menu_on_demand",
+            "file": "calibration.json",
+            "label": {"es": "Menú bajo demanda", "en": "Menu on demand"},
+            "type": "boolean",
+            "group": "preferences",
+            "default": True,
+        },
+        {
+            "path": "preferences.show_pending_items",
+            "file": "calibration.json",
+            "label": {"es": "Mostrar pendientes al inicio", "en": "Show pending items at startup"},
+            "type": "boolean",
+            "group": "preferences",
+            "default": False,
+        },
+        {
+            "path": "preferences.execution_first",
+            "file": "calibration.json",
+            "label": {"es": "Ejecuta antes de preguntar", "en": "Execute before asking"},
+            "type": "boolean",
+            "group": "preferences",
+            "default": True,
+        },
+        {
+            "path": "preferences.report_style",
+            "file": "calibration.json",
+            "label": {"es": "Estilo de reporte", "en": "Report style"},
+            "type": "select",
+            "group": "preferences",
+            "options": [
+                {"value": "essentials_only", "label": {"es": "Solo esencial", "en": "Essentials only"}},
+                {"value": "balanced", "label": {"es": "Equilibrado", "en": "Balanced"}},
+                {"value": "verbose", "label": {"es": "Detallado", "en": "Verbose"}},
+            ],
+        },
+        {
+            "path": "meta.role",
+            "file": "calibration.json",
+            "label": {"es": "Rol / ocupación", "en": "Role / occupation"},
+            "type": "text",
+            "group": "about_you",
+        },
+        {
+            "path": "meta.technical_level",
+            "file": "calibration.json",
+            "label": {"es": "Nivel técnico", "en": "Technical level"},
+            "type": "select",
+            "group": "about_you",
+            "options": [
+                {"value": "beginner", "label": {"es": "Principiante", "en": "Beginner"}},
+                {"value": "intermediate", "label": {"es": "Intermedio", "en": "Intermediate"}},
+                {"value": "advanced", "label": {"es": "Avanzado", "en": "Advanced"}},
+            ],
+        },
+    ]
+
+
+def _schema_groups() -> list[dict]:
+    return [
+        {"id": "personal", "label": {"es": "Personal", "en": "Personal"}, "order": 1},
+        {"id": "personality", "label": {"es": "Personalidad", "en": "Personality"}, "order": 2},
+        {"id": "preferences", "label": {"es": "Preferencias", "en": "Preferences"}, "order": 3},
+        {"id": "about_you", "label": {"es": "Sobre ti", "en": "About you"}, "order": 4},
+    ]
+
+
+def cmd_schema(args) -> int:
+    payload = {
+        "schema_version": SCHEMA_VERSION,
+        "groups": _schema_groups(),
+        "fields": _schema_fields(),
+    }
+    return _print_json(payload)
+
+
+# ---------------------------------------------------------------- identity
+
+def _resolve_identity() -> dict:
+    """Resolve the canonical assistant name + which source produced it."""
+    cal = _read_json(_calibration_path())
+    prof = _read_json(_profile_path())
+
+    probes: list[tuple[str, Any]] = [
+        ("calibration.user.assistant_name",
+         cal.get("user", {}).get("assistant_name") if isinstance(cal.get("user"), dict) else None),
+        ("calibration.operator_name", cal.get("operator_name")),
+        ("calibration.assistant_name", cal.get("assistant_name")),
+        ("calibration.identity", cal.get("identity")),
+        ("profile.operator_name", prof.get("operator_name")),
+        ("profile.assistant_name", prof.get("assistant_name")),
+    ]
+    for source, value in probes:
+        if isinstance(value, str) and value.strip():
+            return {"name": value.strip(), "source": source,
+                    "writable_source": "calibration.user.assistant_name"}
+
+    return {"name": "NEXO", "source": "default",
+            "writable_source": "calibration.user.assistant_name"}
+
+
+def cmd_identity(args) -> int:
+    return _print_json(_resolve_identity())
+
+
+# ---------------------------------------------------------------- onboard
+
+def _onboard_steps() -> list[dict]:
+    return [
+        {
+            "id": "name",
+            "prompt": {"es": "¿Cómo te llamas?", "en": "What's your name?"},
+            "type": "text",
+            "writes": "user.name",
+            "file": "calibration.json",
+            "optional": False,
+            "validate": r"^\S.{0,60}$",
+        },
+        {
+            "id": "language",
+            "prompt": {"es": "¿En qué idioma quieres operar?", "en": "Which language should we use?"},
+            "type": "select",
+            "writes": "user.language",
+            "file": "calibration.json",
+            "optional": False,
+            "default": "es",
+            "options": [
+                {"value": "es", "label": {"es": "Español", "en": "Spanish"}},
+                {"value": "en", "label": {"es": "Inglés", "en": "English"}},
+            ],
+        },
+        {
+            "id": "assistant_name",
+            "prompt": {"es": "¿Cómo se llamará tu asistente?", "en": "What will your assistant be called?"},
+            "type": "text",
+            "writes": "user.assistant_name",
+            "file": "calibration.json",
+            "optional": True,
+            "default": "NEXO",
+        },
+        {
+            "id": "role",
+            "prompt": {"es": "¿A qué te dedicas?", "en": "What do you do?"},
+            "type": "text",
+            "writes": "meta.role",
+            "file": "calibration.json",
+            "optional": True,
+        },
+        {
+            "id": "technical_level",
+            "prompt": {"es": "¿Cuál es tu nivel técnico?", "en": "What's your technical level?"},
+            "type": "select",
+            "writes": "meta.technical_level",
+            "file": "calibration.json",
+            "optional": True,
+            "default": "intermediate",
+            "options": [
+                {"value": "beginner", "label": {"es": "Principiante", "en": "Beginner"}},
+                {"value": "intermediate", "label": {"es": "Intermedio", "en": "Intermediate"}},
+                {"value": "advanced", "label": {"es": "Avanzado", "en": "Advanced"}},
+            ],
+        },
+        {
+            "id": "welcome",
+            "type": "welcome",
+            "message": {
+                "es": "Listo. A partir de ahora aprendo observándote. Dime qué necesitas.",
+                "en": "Ready. From now on I learn by watching. Tell me what you need.",
+            },
+        },
+    ]
+
+
+def cmd_onboard(args) -> int:
+    payload = {
+        "onboard_version": ONBOARD_VERSION,
+        "steps": _onboard_steps(),
+    }
+    return _print_json(payload)
+
+
+# ------------------------------------------------------------ scan-profile
+
+# Patterns we try to lift from the user's CLAUDE.md into profile.json.
+# Kept deliberately narrow to avoid false positives.
+_CLAUDE_MD_CANDIDATES = [
+    Path.home() / ".claude" / "CLAUDE.md",
+    Path.home() / "CLAUDE.md",
+]
+
+
+def _read_claude_md() -> str:
+    for p in _CLAUDE_MD_CANDIDATES:
+        try:
+            if p.is_file():
+                return p.read_text(errors="ignore")
+        except Exception:
+            continue
+    return ""
+
+
+def _guess_role(claude_md: str, cal: dict) -> str:
+    meta_role = cal.get("meta", {}).get("role") if isinstance(cal.get("meta"), dict) else None
+    if isinstance(meta_role, str) and meta_role.strip():
+        return meta_role.strip()
+    m = re.search(r"(?im)^\s*[-*]?\s*(?:role|rol|ocupaci[oó]n|dedica)\s*[:=]\s*(.+)$", claude_md)
+    if m:
+        return m.group(1).strip().strip(".")
+    return ""
+
+
+def _guess_technical_level(claude_md: str, cal: dict) -> str:
+    meta_tl = cal.get("meta", {}).get("technical_level") if isinstance(cal.get("meta"), dict) else None
+    if isinstance(meta_tl, str) and meta_tl.strip():
+        return meta_tl.strip()
+    text = claude_md.lower()
+    if "advanced" in text or "avanzado" in text or "senior" in text:
+        return "advanced"
+    if "intermediate" in text or "intermedio" in text:
+        return "intermediate"
+    if "beginner" in text or "principiante" in text:
+        return "beginner"
+    return ""
+
+
+def _guess_timezone(cal: dict) -> str:
+    tz = cal.get("user", {}).get("timezone") if isinstance(cal.get("user"), dict) else None
+    if isinstance(tz, str) and tz.strip():
+        return tz.strip()
+    return os.environ.get("TZ", "") or ""
+
+
+def _build_profile_payload() -> dict:
+    cal = _read_json(_calibration_path())
+    claude_md = _read_claude_md()
+
+    user = cal.get("user", {}) if isinstance(cal.get("user"), dict) else {}
+    payload = {
+        "version": 1,
+        "source": "scan-profile",
+        "user": {
+            "name": user.get("name", "") or "",
+            "language": user.get("language", "") or "",
+            "timezone": _guess_timezone(cal),
+        },
+        "meta": {
+            "role": _guess_role(claude_md, cal),
+            "technical_level": _guess_technical_level(claude_md, cal),
+        },
+        "signals": {
+            "has_claude_md": bool(claude_md),
+            "claude_md_chars": len(claude_md),
+            "calibration_present": bool(cal),
+        },
+    }
+    return payload
+
+
+def cmd_scan_profile(args) -> int:
+    profile_path = _profile_path()
+    payload = _build_profile_payload()
+    use_json = bool(getattr(args, "json", False))
+    apply = bool(getattr(args, "apply", False))
+    force = bool(getattr(args, "force", False))
+
+    status = "preview"
+    written = False
+    reason = ""
+
+    if apply:
+        if profile_path.exists() and not force:
+            status = "skipped"
+            reason = "profile.json already exists (use --force to overwrite)"
+        else:
+            try:
+                profile_path.parent.mkdir(parents=True, exist_ok=True)
+                profile_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2))
+                status = "written"
+                written = True
+            except Exception as exc:
+                status = "error"
+                reason = f"write failed: {exc}"
+
+    result = {
+        "status": status,
+        "path": str(profile_path),
+        "written": written,
+        "reason": reason,
+        "payload": payload,
+    }
+
+    if use_json:
+        return _print_json(result)
+
+    # Human-readable fallback
+    sys.stdout.write(f"scan-profile: {status}\n")
+    sys.stdout.write(f"  path:    {profile_path}\n")
+    if reason:
+        sys.stdout.write(f"  reason:  {reason}\n")
+    sys.stdout.write("  preview:\n")
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
+    return 0 if status != "error" else 1