{
  "report_info": {
    "version": "9.0.1",
    "generated_at": "2026-07-21T01:54:35Z",
    "binary_name": "logs-hook"
  },
  "binary": {
    "name": "logs-hook",
    "path": "/opt/kodachi/dashboard/hooks/logs-hook",
    "timestamp": "2026-07-21T01:54:35Z",
    "file_info": {
      "size": 1749696,
      "sha256": "ce936d4a0b20310be6c0c7e0d3f5aec9631bde236a1439b36d8ab51389b36107"
    },
    "flag_n": {
      "command": "info",
      "data": {
        "author": "Warith Al Maawali",
        "copyright": "© 2026 Kodachi OS",
        "description": "A robust, secure, and configurable logging system for Kodachi OS",
        "features": [
          "Centralized logging system",
          "Log rotation with configurable limits",
          "Secure log wiping",
          "Multiple log levels support",
          "JSON output format",
          "Embedded configuration system"
        ],
        "license": "Proprietary",
        "name": "logs-hook",
        "securityFeatures": {
          "authentication": "Not implemented in this crate (online-auth is a separate binary)",
          "encryption": "Not implemented in this crate (log files are stored as plain text)",
          "inputValidation": "Sanitizes script names and messages",
          "rateLimiting": "Not implemented in this crate (handled externally if required)"
        },
        "systemRequirements": {
          "dependencies": [
            "tokio runtime",
            "filesystem access"
          ],
          "os": "Linux (Debian-based)",
          "privileges": "root/sudo for system logs"
        },
        "version": "9.8.4",
        "website": "https://digi77.com"
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:35.314280647Z",
      "version": "9.8.4",
      "warnings": []
    },
    "flag_v": {
      "command": "version",
      "data": {
        "buildDate": "REDACTED-BUILD-TIME",
        "gitCommit": "unknown",
        "name": "logs-hook",
        "rustVersion": "1.88.0",
        "version": "9.8.4"
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:35.416934899Z",
      "version": "9.8.4",
      "warnings": []
    },
    "flag_h": {
      "command": "help",
      "data": {
        "commandCategories": [
          {
            "category": "Logging Commands",
            "commands": [
              {
                "description": "Log a message",
                "examples": [
                  "logs-hook log --script 'my-script' --level info 'Script started'",
                  "logs-hook log -s 'backup' -l warn 'Low disk space'",
                  "logs-hook log --script 'app' --level error 'Connection failed' --json"
                ],
                "name": "log",
                "options": [
                  {
                    "description": "Script name for the log entry",
                    "flag": "--script, -s <SCRIPT>",
                    "required": true
                  },
                  {
                    "default": "info",
                    "description": "Log level (info, warn, error, debug, fatal)",
                    "flag": "--level, -l <LEVEL>",
                    "required": false
                  }
                ],
                "requires_sudo": false,
                "usage": "logs-hook log --script <SCRIPT> --level <LEVEL> <MESSAGE>"
              }
            ]
          },
          {
            "category": "Maintenance Commands",
            "commands": [
              {
                "description": "Rotate a specific log file (--file is required)",
                "examples": [
                  "logs-hook maintenance rotate --file /path/to/log.txt",
                  "logs-hook maintenance rotate --file /path/to/log.txt --json"
                ],
                "name": "maintenance rotate",
                "options": [
                  {
                    "description": "Log file to rotate (required; rotate-all is not supported)",
                    "flag": "--file, -f <FILE>",
                    "required": true
                  }
                ],
                "requires_sudo": false,
                "usage": "logs-hook maintenance rotate --file <FILE>"
              },
              {
                "description": "Wipe log files (--all, --file, or --confirm is required)",
                "examples": [
                  "logs-hook maintenance wipe --all",
                  "logs-hook maintenance wipe --file /path/to/log.txt",
                  "logs-hook maintenance wipe --all --json",
                  "logs-hook maintenance wipe --confirm"
                ],
                "name": "maintenance wipe",
                "options": [
                  {
                    "description": "Wipe all logs",
                    "flag": "--all, -a",
                    "required": false
                  },
                  {
                    "description": "Specific log file to wipe",
                    "flag": "--file, -f <FILE>",
                    "required": false
                  },
                  {
                    "description": "Explicitly confirm wipe using the default policy (required when neither --all nor --file is given)",
                    "flag": "--confirm",
                    "required": false
                  }
                ],
                "requires_sudo": false,
                "usage": "logs-hook maintenance wipe (--all | --file <FILE> | --confirm)"
              }
            ]
          },
          {
            "category": "Help Commands",
            "commands": [
              {
                "description": "Show targeted help for a command path (handled before clap parsing)",
                "examples": [
                  "logs-hook help",
                  "logs-hook help log",
                  "logs-hook help maintenance wipe"
                ],
                "name": "help",
                "options": [],
                "requires_sudo": false,
                "usage": "logs-hook help [<COMMAND> [<SUBCOMMAND>]]"
              }
            ]
          }
        ],
        "description": "A robust, secure, and configurable logging system for Kodachi OS",
        "environmentVariables": [
          {
            "default": "info",
            "description": "Set logging level",
            "name": "RUST_LOG",
            "values": "error|warn|info|debug|trace"
          },
          {
            "default": "unset",
            "description": "Disable all colored output when set",
            "name": "NO_COLOR",
            "values": "1|true|yes (any value disables color)"
          },
          {
            "default": "auto-detected",
            "description": "Base directory for logs",
            "name": "KODACHI_BASE_DIR",
            "values": "/path/to/base/dir"
          },
          {
            "default": "current directory",
            "description": "Working directory for logging operations",
            "name": "LOGS_HOOK_WORK_DIR",
            "values": "/path/to/work/dir"
          }
        ],
        "exitCodes": {
          "0": "Success",
          "1": "General error",
          "2": "Invalid arguments",
          "3": "Permission denied",
          "4": "Network error",
          "5": "File not found"
        },
        "globalOptions": [
          {
            "description": "Print help information",
            "flag": "-h, --help"
          },
          {
            "description": "Print version information",
            "flag": "-v, --version"
          },
          {
            "description": "Display detailed information",
            "flag": "-n, --info"
          },
          {
            "description": "Show usage examples",
            "flag": "-e, --examples"
          },
          {
            "description": "Output in JSON format",
            "flag": "--json"
          },
          {
            "description": "Pretty-print JSON output",
            "flag": "--json-pretty"
          },
          {
            "description": "Enhanced, colorized JSON output (jq-style); implies --json",
            "flag": "--json-human"
          },
          {
            "description": "Set CLI log level, error|warn|info|debug (parsed globally; not applied by logs-hook, use the log --level flag instead)",
            "flag": "--log-level <LEVEL>"
          },
          {
            "description": "Filter JSON output fields (parsed globally; not applied by logs-hook)",
            "flag": "--json-filter <FIELDS>"
          },
          {
            "description": "Enable verbose output (parsed globally; not applied by logs-hook)",
            "flag": "--verbose"
          },
          {
            "description": "Suppress non-essential output (parsed globally; not applied by logs-hook)",
            "flag": "--quiet"
          },
          {
            "description": "Disable colored output",
            "flag": "--no-color"
          },
          {
            "description": "Set timeout (parsed globally; not applied by logs-hook)",
            "flag": "-t, --timeout <SECS>"
          },
          {
            "description": "Working directory (defaults to auto-detected base directory)",
            "flag": "-d, --work-dir <PATH>"
          },
          {
            "description": "Force output format (default: text)",
            "flag": "-o, --output-format <FORMAT>"
          },
          {
            "description": "Configuration file path (parsed globally; logs-hook uses embedded config only)",
            "flag": "--config <FILE>"
          },
          {
            "description": "Select specific fields to include in output (parsed globally; not applied by logs-hook)",
            "flag": "--fields <FIELD_LIST>"
          },
          {
            "description": "Limit number of results returned (parsed globally; not applied by logs-hook)",
            "flag": "--limit <NUMBER>"
          },
          {
            "description": "Skip first N results for pagination (parsed globally; not applied by logs-hook)",
            "flag": "--offset <NUMBER>"
          }
        ],
        "name": "logs-hook",
        "usage": "logs-hook [OPTIONS] [COMMAND] [ARGS]"
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:35.527642485Z",
      "version": "9.8.4",
      "warnings": []
    },
    "flag_e": {
      "command": "examples",
      "data": {
        "categories": [
          {
            "description": "Writing log entries. logs-hook does not require root: it appends to <base_dir>/logs/<script>-log.log, where <base_dir> is auto-detected (or set with --work-dir / KODACHI_BASE_DIR). Run it as the user that owns that directory.",
            "examples": [
              {
                "command": "logs-hook log --script 'my-script' --level info 'Script started'",
                "description": "Log an info message from a script",
                "expectedOutput": "Message logged successfully (appends '2026-07-13 09:14:02 UTC [INFO] | my-script: Script started' to <base_dir>/logs/my-script-log.log)"
              },
              {
                "command": "logs-hook log -s 'backup' -l warn 'Low disk space'",
                "description": "Log a warning using the short flags",
                "expectedOutput": "Message logged successfully (line appended to <base_dir>/logs/backup-log.log)"
              },
              {
                "command": "logs-hook log --script 'app' --level error 'Connection failed'",
                "description": "Log an error",
                "expectedOutput": "Message logged successfully",
                "notes": "--level accepts info, warn, error, debug or fatal. It defaults to info, and --script plus the message are both required."
              },
              {
                "command": "logs-hook log --script 'app' --level debug 'Verbose trace'",
                "description": "Log a debug message",
                "expectedOutput": "Message logged successfully"
              },
              {
                "command": "logs-hook log --script 'app' --level fatal 'Unrecoverable failure'",
                "description": "Log a fatal message",
                "expectedOutput": "Message logged successfully",
                "notes": "Fatal is the highest severity; reserve it for unrecoverable conditions"
              }
            ],
            "id": "1_basic_usage",
            "title": "Basic Usage"
          },
          {
            "description": "Rotating and wiping log files. Wiping is IRREVERSIBLE: there are three distinct wipe paths (--all, --file and --confirm) and they do not target the same files.",
            "examples": [
              {
                "command": "logs-hook maintenance rotate --file <BASE_DIR>/logs/app-log.log",
                "description": "Force-rotate one log file to a numbered backup",
                "expectedOutput": "Log rotation completed for: \"<BASE_DIR>/logs/app-log.log\"",
                "notes": "--file is required and the file must exist; rotate-all is not supported. A bare 'maintenance rotate' exits 2."
              },
              {
                "command": "logs-hook maintenance wipe --all",
                "description": "Wipe every log file in the log directory",
                "expectedOutput": "All logs wiped successfully",
                "notes": "DESTRUCTIVE and irreversible: this clears every log in <base_dir>/logs, not just the ones a policy selects. Rotate first if you need the history."
              },
              {
                "command": "logs-hook maintenance wipe --file <BASE_DIR>/logs/app-log.log",
                "description": "Wipe one named log file",
                "expectedOutput": "Log wiped successfully: \"<BASE_DIR>/logs/app-log.log\"",
                "notes": "DESTRUCTIVE and irreversible for that file. The file must exist and be writable, otherwise the command exits 1 with FILE_NOT_FOUND."
              },
              {
                "command": "logs-hook maintenance wipe --confirm",
                "description": "Wipe logs using the configured retention policy",
                "expectedOutput": "Logs wiped based on configuration",
                "notes": "DESTRUCTIVE and irreversible. Different from --all: it wipes only what the embedded log-hook-config policy targets (all logs, or just the ones past the retention condition). --confirm is required whenever neither --all nor --file is given; a bare 'maintenance wipe' is refused."
              }
            ],
            "id": "2_maintenance",
            "title": "Maintenance Operations"
          },
          {
            "description": "Redirecting the log tree and running against a root-owned hooks directory.",
            "examples": [
              {
                "command": "logs-hook --work-dir /custom/path log --script 'debug' --level info 'Custom directory test'",
                "description": "Write to a different base directory instead of the auto-detected one",
                "expectedOutput": "Message logged successfully (line appended to /custom/path/logs/debug-log.log)",
                "notes": "--work-dir is created if missing and also sets KODACHI_BASE_DIR and LOGS_HOOK_WORK_DIR for this run. It must be a directory, not a file."
              },
              {
                "command": "sudo logs-hook log --script 'installer' --level info 'Deployed'",
                "description": "Log into a root-owned base directory (for example the deployed /opt hooks tree)",
                "expectedOutput": "Message logged successfully",
                "notes": "This is the ONLY case that needs sudo: logs-hook itself does not require root, it only needs write access to <base_dir>/logs. Under sudo it restores the log file's ownership to the invoking user afterwards."
              },
              {
                "command": "KODACHI_BASE_DIR=/opt/kodachi/dashboard/hooks logs-hook log -s 'cron' -l info 'Nightly job done'",
                "description": "Point logs-hook at a base directory through the environment instead of a flag",
                "expectedOutput": "Message logged successfully (line appended to /opt/kodachi/dashboard/hooks/logs/cron-log.log)"
              }
            ],
            "id": "3_advanced_usage",
            "title": "Advanced Usage"
          },
          {
            "description": "Machine-readable output. Every command returns the standard result envelope (status, command, version, data, duration_ms).",
            "examples": [
              {
                "command": "logs-hook --json log --script 'app' --level error 'Connection failed'",
                "description": "Log a message and get the result envelope back as compact JSON",
                "expectedOutput": "{\"status\":\"success\",\"command\":\"log\",\"data\":{\"success\":true,\"message\":\"Message logged successfully\",\"script\":\"app\",\"level\":\"Error\",\"timestamp\":\"2026-07-13T09:14:02Z\"}, ...}"
              },
              {
                "command": "logs-hook --json-pretty log -s 'test' -l info 'Test'",
                "description": "Same envelope, indented for reading",
                "expectedOutput": "Indented JSON envelope with the log result"
              },
              {
                "command": "logs-hook --json-human maintenance rotate --file <BASE_DIR>/logs/app-log.log",
                "description": "Colorized, jq-style JSON for reading at a terminal",
                "expectedOutput": "Highlighted JSON envelope with operation 'rotate' and the resolved absolute file path",
                "notes": "--json-human implies JSON mode; do not pipe it to a parser, use --json for that."
              },
              {
                "command": "logs-hook -v --json",
                "description": "Version as JSON",
                "expectedOutput": "JSON envelope carrying name, version and build metadata"
              },
              {
                "command": "logs-hook -n --json",
                "description": "Program info (features, security posture, requirements) as JSON",
                "expectedOutput": "JSON envelope with the program info block"
              },
              {
                "command": "logs-hook maintenance wipe --all --json",
                "description": "Wipe every log and capture the outcome for a script",
                "expectedOutput": "{\"status\":\"success\",\"command\":\"maintenance wipe\",\"data\":{\"operation\":\"wipe_all\",\"message\":\"All logs wiped successfully\"}, ...}",
                "notes": "DESTRUCTIVE and irreversible: --json only changes the reporting, not the effect."
              }
            ],
            "id": "4_json_output",
            "title": "JSON Output"
          },
          {
            "description": "Discovering the exact flags of a subcommand and checking where output is going.",
            "examples": [
              {
                "command": "logs-hook help maintenance wipe",
                "description": "Show the full help for one command path without running it",
                "expectedOutput": "The clap long help for 'maintenance wipe', listing --all, --file and --confirm",
                "notes": "'logs-hook help [<COMMAND> [<SUBCOMMAND>]]' is handled before argument parsing, so it works for 'log', 'maintenance', 'maintenance rotate' and 'maintenance wipe'. Bare 'logs-hook help' prints the top-level help."
              },
              {
                "command": "logs-hook --no-color --json log --script 'debug' --level debug 'Debug info'",
                "description": "Log without ANSI colour codes, for capture into a file or a CI log",
                "expectedOutput": "Plain JSON envelope with no escape sequences"
              },
              {
                "command": "logs-hook --work-dir /custom/path --json log -s 'pathcheck' -l info 'where did this go'",
                "description": "Confirm which directory a log actually landed in when the base directory is ambiguous",
                "expectedOutput": "Success envelope; the line is in /custom/path/logs/pathcheck-log.log",
                "notes": "logs-hook accepts --verbose, --quiet, --timeout, --fields, --limit and --offset because they are cli-core globals, but it does not act on them. Use --work-dir and the JSON envelope to diagnose path problems."
              }
            ],
            "id": "5_troubleshooting",
            "title": "Troubleshooting"
          }
        ],
        "description": "Usage examples for logs-hook",
        "name": "logs-hook",
        "quickReference": [
          "logs-hook --help",
          "logs-hook --version",
          "logs-hook --info --json",
          "logs-hook --examples --json",
          "logs-hook help maintenance wipe",
          "logs-hook log -s 'test' -l info 'message'",
          "logs-hook maintenance rotate --file <BASE_DIR>/logs/app-log.log",
          "logs-hook maintenance wipe --all",
          "logs-hook maintenance wipe --file <BASE_DIR>/logs/app-log.log",
          "logs-hook maintenance wipe --confirm",
          "logs-hook --work-dir /custom/path log -s 'test' -l info 'msg'"
        ]
      },
      "errors": [],
      "metadata": {
        "executionTime": 0,
        "hostname": "REDACTED-BUILD-HOST",
        "user": "REDACTED-BUILD-USER"
      },
      "status": "success",
      "timestamp": "2026-07-21T01:54:35.764607720Z",
      "version": "9.8.4",
      "warnings": []
    }
  }
}