feat: runnable onboarding quickstart, recipes, and fixtures (issue #32)

.luacheckrc

@@ -12,7 +12,7 @@ globals = {
 max_line_length = 140
 
 -- Exclude generated or vendored paths
-exclude_files = { "spec/helpers/mock_ngx.lua" }
+exclude_files = { "spec/helpers/mock_ngx.lua", "cli/lib/mock_ngx.lua" }
 
 -- Test files monkey-patch standard globals (math.random, os.getenv)
 -- and use intentionally-unused callback arguments (self, ctx).

bin/ci/check_unpinned_dependencies.py

@@ -13,7 +13,7 @@
 SHA_RE = re.compile(r"^[0-9a-f]{40}$")
 USES_RE = re.compile(r"uses:\s*([^\s#]+)")
 FROM_RE = re.compile(r"^\s*FROM\s+([^\s]+)", re.MULTILINE)
-OPM_RE = re.compile(r"^\s*RUN\s+opm\s+get\s+([^\s\\]+)(?:\s+([^\s\\#]+))?", re.MULTILINE)
+OPM_RE = re.compile(r"^\s*RUN\s+opm\s+get\s+([^\s\\]+)(?:[^\S\n]+([^\s\\#]+))?", re.MULTILINE)
 
 
 @dataclass(frozen=True)
@@ -79,7 +79,9 @@ def scan_dockerfile(path: Path) -> list[Finding]:
     for match in OPM_RE.finditer(text):
         package = match.group(1)
         version = match.group(2)
-        if not version or version.startswith(("&", "|")):
+        # OPM uses "pkg=version" (embedded) or "pkg version" (space-separated)
+        is_pinned = "=" in package or (version and not version.startswith(("&", "|")))
+        if not is_pinned:
             findings.append(
                 Finding(
                     category="opm-package",

bin/fairvisor

@@ -3,5 +3,5 @@
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 
-exec resty -I "${SCRIPT_DIR}/src" -I "${SCRIPT_DIR}/cli" \
+exec resty -I "${SCRIPT_DIR}/src" -I "${SCRIPT_DIR}" \
   "${SCRIPT_DIR}/cli/main.lua" "$@"

cli/README.md

@@ -18,10 +18,10 @@ From the repo root:
 Or with `resty` directly (e.g. from another directory, adjusting `-I` paths):
 
 ```bash
-resty -I /path/to/fv-oss/src -I /path/to/fv-oss/cli /path/to/fv-oss/cli/main.lua <command> [options]
+resty -I /path/to/fv-oss/src -I /path/to/fv-oss /path/to/fv-oss/cli/main.lua <command> [options]
 ```
 
-`bin/fairvisor` sets `-I` to the repo's `src` and `cli` so that `require("cli.commands.init")` and `require("fairvisor.bundle_loader")` resolve correctly.
+`bin/fairvisor` sets `-I` to the repo's `src` and root (for `cli.*` modules) so that `require("cli.commands.init")` and `require("fairvisor.bundle_loader")` resolve correctly.
 
 ## Commands
 

cli/commands/status.lua

@@ -41,14 +41,28 @@ function _M.run(argv)
     return nil, 2
   end
 
+  local policy_version = "unknown"
+  if health_res.body and health_res.body ~= "" then
+    local ok_json, cjson = pcall(require, "cjson")
+    if ok_json then
+      local ok_dec, decoded = pcall(cjson.decode, health_res.body)
+      if ok_dec and type(decoded) == "table" and decoded.policy_version ~= nil then
+        policy_version = tostring(decoded.policy_version)
+      end
+    end
+  end
+
   local metrics_res = httpc:request_uri(edge_url .. "/metrics")
   local metrics_body = metrics_res and metrics_res.body or ""
 
+  local decisions_raw = _parse_metric(metrics_body, "fairvisor_decisions_total")
+  local decisions = (decisions_raw ~= "unknown") and decisions_raw or "0"
+
   local data = {
     status = (health_res.status == 200 and "ready") or "not ready",
-    policy_version = _parse_metric(metrics_body, "fairvisor_bundle_version"),
+    policy_version = policy_version,
     saas = (_parse_metric(metrics_body, "fairvisor_saas_reachable") == "1") and "connected" or "disconnected",
-    decisions = _parse_metric(metrics_body, "fairvisor_decisions_total"),
+    decisions = decisions,
   }
 
   if format == "json" then

cli/commands/test.lua

@@ -15,6 +15,9 @@ local function _read_file(path)
 
   local content = handle:read("*a")
   handle:close()
+  if content == nil then
+    return nil, "failed to read file content"
+  end
   return content
 end
 
@@ -47,7 +50,7 @@ local function _generate_mock_requests(bundle)
       headers = {},
       query_params = {},
       ip_address = "127.0.0.1",
-      user_agent = "fairvisor-cli/test",
+      user_agent = "fairvisor/test",
     }
   end
 
@@ -58,7 +61,7 @@ local function _generate_mock_requests(bundle)
       headers = {},
       query_params = {},
       ip_address = "127.0.0.1",
-      user_agent = "fairvisor-cli/test",
+      user_agent = "fairvisor/test",
     }
   end
 
@@ -127,7 +130,7 @@ function _M.run(argv)
 
   local content, read_err = _read_file(file)
   if not content then
-    output.print_error("Cannot read file: " .. read_err)
+    output.print_error("Cannot read file: " .. (read_err or "unknown read error"))
     return nil, 1
   end
 
@@ -142,7 +145,7 @@ function _M.run(argv)
     return nil, 1
   end
 
-  local ok_mock, mock_ngx = pcall(require, "spec.helpers.mock_ngx")
+  local ok_mock, mock_ngx = pcall(require, "cli.lib.mock_ngx")
   if not ok_mock then
     output.print_error("mock_ngx helper is unavailable: " .. mock_ngx)
     return nil, 1
@@ -168,7 +171,7 @@ function _M.run(argv)
   if requests_file then
     requests, read_err = _load_requests(requests_file)
     if not requests then
-      output.print_error("Cannot load requests: " .. read_err)
+      output.print_error("Cannot load requests: " .. (read_err or "unknown read error"))
       return nil, 1
     end
   else

cli/commands/validate.lua

@@ -20,6 +20,9 @@ local function _read_file(path)
 
   local content = handle:read("*a")
   handle:close()
+  if content == nil then
+    return nil, "failed to read file content"
+  end
   return content
 end
 
@@ -101,7 +104,7 @@ function _M.run(argv)
 
   local content, read_err = _read_file(file)
   if not content then
-    output.print_error("Cannot read file: " .. read_err)
+    output.print_error("Cannot read file: " .. (read_err or "unknown read error"))
     return nil, 1
   end