dep-fetcher 0.1.2: multi-path resolution + accept untagged dev-state when manifest matches pin

- resolve_libs_dirs / resolve_modules_dirs return arrays of candidate
  paths (priority: opts override > opts.install_root-derived >
  engine.libs_dirs() / modules_dirs() > SPOREL_*_DIR env >
  install_root-derived fallback). first_existing walks the array to
  find the candidate that actually contains the requested manifest,
  so dev-tree layouts with libs and modules in different roots work
  without forcing the caller to pre-flatten.
- New case G: when describe fails because the repo has no tags at
  all (common during dev between tagged releases), accept the lib
  if its manifest.version matches the pin. Previously errored as
  "describe-fail" which made the pre-launch dep-check unusable in
  dev-tree runs.
- Dep pin: lib-core.git 0.1.0 -> 0.2.0 (token-auth + set_token).

init.lua

@@ -32,6 +32,130 @@
 
 local M = {}
 
+-- =====================================================================
+-- Engine binding probes (Slice 6)
+--
+-- Slice 6 of the dep-fetcher plan wired engine.install_root() and
+-- engine.config(key) as Lua-level bindings. We probe for them at
+-- call-time (not load-time) so this lib continues to load under
+-- engines that pre-date Slice 6 — the fallbacks (env var, hardcoded
+-- URL) keep slice-5-compat with unmodified hosts.
+-- =====================================================================
+
+local function resolve_install_root(opts)
+    -- 1. explicit override
+    if opts and opts.install_root then return opts.install_root end
+    -- 2. Slice 6 engine binding
+    if type(engine) == "table"
+       and type(engine.install_root) == "function" then
+        local ok, root = pcall(engine.install_root)
+        if ok and type(root) == "string" and root ~= "" then
+            return root
+        end
+    end
+    -- 3. Slice 5 stop-gap: env var
+    return os.getenv("SPOREL_INSTALL_ROOT")
+end
+
+-- Slice 6.1: libs and modules can live in many roots simultaneously
+-- (multi-path engine discovery, dev-tree SPOREL_*_DIR overrides). Each
+-- resolver returns an ARRAY of candidate paths (priority-ordered);
+-- callers iterate to find the first that contains the requested file.
+--
+-- Priority order:
+--   1. opts.libs_dir / opts.modules_dir explicit override (always wins)
+--   2. opts.install_root explicit override -> derive `<root>/{libs,modules}`
+--      (tests pass install_root pointing at a fixture; the engine
+--      bindings would otherwise return the real engine paths, masking
+--      the fixture)
+--   3. engine.{libs,modules}_dirs() — runtime discovery candidates
+--   4. SPOREL_{LIBS,MODULES}_DIR env var
+--   5. Auto-resolved install_root -> `<root>/{libs,modules}` (last resort)
+local function resolve_libs_dirs(opts, install_root)
+    local list = {}
+    if opts and opts.libs_dir then table.insert(list, opts.libs_dir) end
+    if opts and opts.install_root then
+        table.insert(list, opts.install_root .. "/libs")
+    end
+    if type(engine) == "table"
+       and type(engine.libs_dirs) == "function" then
+        local ok, dirs = pcall(engine.libs_dirs)
+        if ok and type(dirs) == "table" then
+            for _, d in ipairs(dirs) do
+                if type(d) == "string" and d ~= "" then
+                    table.insert(list, d)
+                end
+            end
+        end
+    end
+    local env = os.getenv("SPOREL_LIBS_DIR")
+    if env and env ~= "" then table.insert(list, env) end
+    if install_root then table.insert(list, install_root .. "/libs") end
+    return list
+end
+
+local function resolve_modules_dirs(opts, install_root)
+    local list = {}
+    if opts and opts.modules_dir then table.insert(list, opts.modules_dir) end
+    if opts and opts.install_root then
+        table.insert(list, opts.install_root .. "/modules")
+    end
+    if type(engine) == "table"
+       and type(engine.modules_dirs) == "function" then
+        local ok, dirs = pcall(engine.modules_dirs)
+        if ok and type(dirs) == "table" then
+            for _, d in ipairs(dirs) do
+                if type(d) == "string" and d ~= "" then
+                    table.insert(list, d)
+                end
+            end
+        end
+    end
+    local env = os.getenv("SPOREL_MODULES_DIR")
+    if env and env ~= "" then table.insert(list, env) end
+    if install_root then table.insert(list, install_root .. "/modules") end
+    return list
+end
+
+-- Helper: filesystem existence check via io.open. Used to pick the
+-- first multi-path candidate that actually has the requested file.
+local function file_exists(path)
+    local f = io.open(path, "rb")
+    if not f then return false end
+    f:close()
+    return true
+end
+
+-- Given a list of candidate dirs and a relative file-path, return the
+-- first <dir>/<rel> that exists, or nil if none.
+local function first_existing(dirs, rel_path)
+    for _, d in ipairs(dirs) do
+        local p = d .. "/" .. rel_path
+        if file_exists(p) then return p, d end
+    end
+    return nil, nil
+end
+
+local function resolve_gitea_base(opts)
+    -- 1. explicit override
+    if opts and opts.gitea_base then return opts.gitea_base end
+    -- 2. Slice 6 engine.config("gitea_base") (sourced from engine.json)
+    if type(engine) == "table"
+       and type(engine.config) == "function" then
+        local ok, val = pcall(engine.config, "gitea_base")
+        if ok and type(val) == "string" and val ~= "" then
+            return val
+        end
+    end
+    -- 3. Hardcoded slice-5 fallback
+    return "https://git.davoryn.de/sporel"
+end
+
+M._resolve_install_root = resolve_install_root  -- exposed for tests
+M._resolve_libs_dirs    = resolve_libs_dirs     -- exposed for tests
+M._resolve_modules_dirs = resolve_modules_dirs  -- exposed for tests
+M._resolve_gitea_base   = resolve_gitea_base    -- exposed for tests
+
 -- =====================================================================
 -- Pure-Lua JSON decoder (strict subset: object / array / string /
 -- number / true / false / null). Sufficient for manifest.lib /
@@ -269,9 +393,12 @@ local function id_to_path(lib_id)
 end
 M._id_to_path = id_to_path
 
--- Locate a lib's manifest under <install_root>/libs/<id-path>/.
-local function lib_manifest_path(install_root, lib_id)
-    return install_root .. "/libs/" .. id_to_path(lib_id) .. "/manifest.lib"
+-- Find a lib's manifest across multiple candidate libs_dirs. Returns
+-- (full_path, owning_libs_dir) for the first candidate that exists, or
+-- (nil, nil) if absent everywhere.
+local function find_lib_manifest(libs_dirs, lib_id)
+    return first_existing(libs_dirs,
+        id_to_path(lib_id) .. "/manifest.lib")
 end
 
 -- Gitea-slug derivation. Default: "sporel-" + lib-id verbatim.
@@ -296,7 +423,7 @@ M._gitea_slug_for = gitea_slug_for
 -- Each closure entry records the (source, lib_id, version) pin that the
 -- closure walk observed; multi-pin entries for the same lib_id are kept
 -- intact so detect_conflicts() can group them.
-local function walk_closure(module_manifest_path, install_root)
+local function walk_closure(module_manifest_path, libs_dirs)
     local closure = {}
     local visited = {}
 
@@ -318,7 +445,8 @@ local function walk_closure(module_manifest_path, install_root)
         })
         if not visited[d.id] then
             visited[d.id] = true
-            local m = read_manifest(lib_manifest_path(install_root, d.id))
+            local mpath = find_lib_manifest(libs_dirs, d.id)
+            local m = mpath and read_manifest(mpath) or nil
             if m and m.deps then
                 for _, sub in ipairs(m.deps) do
                     table.insert(queue, { source = m.id, dep = sub })
@@ -377,34 +505,74 @@ M._detect_conflicts = detect_conflicts
 --   C — dirty         : commits-past-tag or working-tree dirty  → warn
 --   D — wrong-tag     : describe != pinned-tag → silent checkout
 --   E — broken        : describe fails entirely                 → error
-local function run_state_check(unique_closure, install_root,
+--   F — packaged      : lib dir exists, no .git/, manifest.lib version
+--                       matches pin → accept (cmake-staged install)
+local function manifest_version_matches(lib_dir, expected_version)
+    local f = io.open(lib_dir .. "/manifest.lib", "rb")
+    if not f then return false end
+    local content = f:read("*a")
+    f:close()
+    local m, _ = json_decode(content)
+    return m ~= nil and m.version == expected_version
+end
+
+local function run_state_check(unique_closure, libs_dirs,
                                gitea_base, warnings, errors)
     local git = require("lib-core.git")
 
     for _, e in ipairs(unique_closure) do
-        local lib_dir   = install_root .. "/libs/" .. id_to_path(e.lib_id)
+        -- Resolve the lib's home: first libs_dir that contains its
+        -- manifest. Falls back to the first candidate so clone targets
+        -- a deterministic location when the lib is missing entirely.
+        local _, owning_dir = find_lib_manifest(libs_dirs, e.lib_id)
+        local libs_dir  = owning_dir or libs_dirs[1]
+        if not libs_dir then
+            table.insert(errors, {
+                lib_id = e.lib_id, kind = "config",
+                message = "no libs_dir candidate for state-check",
+            })
+            goto continue
+        end
+        local lib_dir   = libs_dir .. "/" .. id_to_path(e.lib_id)
         local url       = gitea_base .. "/" .. gitea_slug_for(e.lib_id) .. ".git"
         local pinned    = "v" .. e.version
 
         if not git.is_repo(lib_dir) then
-            -- Case A: clone @ pinned-tag.
-            local ok, gerr = git.clone(url, lib_dir, pinned)
-            if not ok then
-                table.insert(errors, {
-                    lib_id  = e.lib_id,
-                    kind    = "net-fail",
-                    message = tostring(gerr),
-                })
+            -- No .git dir present. Two sub-cases:
+            --   F — packaged install: dir exists with a manifest.lib at
+            --       the right version (cmake --install layout). Accept.
+            --   A — missing: dir absent or manifest mismatch → clone.
+            if manifest_version_matches(lib_dir, e.version) then
+                -- Case F: packaged install, no action needed.
+            else
+                local ok, gerr = git.clone(url, lib_dir, pinned)
+                if not ok then
+                    table.insert(errors, {
+                        lib_id  = e.lib_id,
+                        kind    = "net-fail",
+                        message = tostring(gerr),
+                    })
+                end
             end
         else
             local desc, derr = git.describe(lib_dir)
             if not desc then
-                -- Case E: broken.
-                table.insert(errors, {
-                    lib_id  = e.lib_id,
-                    kind    = "describe-fail",
-                    message = tostring(derr),
-                })
+                -- describe failed. Two sub-cases:
+                --   G — untagged dev-state: repo has no tags at all (common
+                --       when working on master between tagged releases).
+                --       If manifest.version matches pin, the install IS at
+                --       the right code regardless of git refs → accept.
+                --   E — genuinely broken: manifest mismatch + no tags →
+                --       caller has no way to recover, surface error.
+                if manifest_version_matches(lib_dir, e.version) then
+                    -- Case G: untagged but manifest authoritative — accept.
+                else
+                    table.insert(errors, {
+                        lib_id  = e.lib_id,
+                        kind    = "describe-fail",
+                        message = tostring(derr),
+                    })
+                end
             elseif desc == pinned then
                 -- Case B: clean exact match.
             else
@@ -436,6 +604,7 @@ local function run_state_check(unique_closure, install_root,
                 end
             end
         end
+        ::continue::
     end
 end
 
@@ -446,30 +615,36 @@ end
 -- ensure_for_module_at — full integrity check.
 --   module_manifest_path : absolute path to manifest.module
 --   opts:
---     install_root  : root of <staged>/libs/ — defaults to env
---                     SPOREL_INSTALL_ROOT (slice 6: engine.install_root()).
+--     install_root  : root of <staged>/libs/. Resolution chain (Slice 6):
+--                       1. opts.install_root (explicit override)
+--                       2. engine.install_root() if the binding is present
+--                       3. SPOREL_INSTALL_ROOT env var (slice-5 stop-gap)
 --     check_only    : skip per-lib git operations entirely
 --                     (used by closure-shape unit tests).
---     gitea_base    : override default base URL.
+--     gitea_base    : override default base URL. Resolution chain:
+--                       1. opts.gitea_base
+--                       2. engine.config("gitea_base") if available
+--                       3. hardcoded https://git.davoryn.de/sporel fallback
 function M.ensure_for_module_at(module_manifest_path, opts)
     opts = opts or {}
-    local install_root = opts.install_root
-        or os.getenv("SPOREL_INSTALL_ROOT")
-    if not install_root then
+    local install_root = resolve_install_root(opts)
+    local libs_dirs    = resolve_libs_dirs(opts, install_root)
+    if #libs_dirs == 0 then
         return {
             ok = false, conflicts = {}, warnings = {},
             errors = {{
                 lib_id  = "<module>",
                 kind    = "config",
-                message = "no install_root: pass opts.install_root or " ..
-                          "set SPOREL_INSTALL_ROOT (slice 6 will add " ..
-                          "engine.install_root() binding)",
+                message = "no libs_dir candidates: pass opts.libs_dir, set " ..
+                          "SPOREL_LIBS_DIR / SPOREL_INSTALL_ROOT, or run " ..
+                          "under an engine that provides engine.libs_dirs() / " ..
+                          "engine.install_root()",
             }},
             closure = {},
         }
     end
 
-    local closure, werr = walk_closure(module_manifest_path, install_root)
+    local closure, werr = walk_closure(module_manifest_path, libs_dirs)
     if not closure then
         return {
             ok = false, conflicts = {}, warnings = {},
@@ -507,11 +682,10 @@ function M.ensure_for_module_at(module_manifest_path, opts)
         end
     end
 
-    local gitea_base = opts.gitea_base
-        or "https://git.davoryn.de/sporel"
+    local gitea_base = resolve_gitea_base(opts)
 
     local warnings, errors = {}, {}
-    run_state_check(unique, install_root, gitea_base, warnings, errors)
+    run_state_check(unique, libs_dirs, gitea_base, warnings, errors)
 
     return {
         ok       = (#errors == 0),
@@ -523,24 +697,41 @@ function M.ensure_for_module_at(module_manifest_path, opts)
 end
 
 -- Convenience wrapper resolving the module-id via install layout.
--- Slice 6 will replace SPOREL_INSTALL_ROOT with engine.install_root().
+-- Resolves install_root via the same Slice 6 chain as ensure_for_module_at:
+-- explicit opts → engine.install_root() → SPOREL_INSTALL_ROOT env var.
 function M.ensure_for_module(module_id, opts)
     opts = opts or {}
-    local install_root = opts.install_root
-        or os.getenv("SPOREL_INSTALL_ROOT")
-    if not install_root then
+    local install_root = resolve_install_root(opts)
+    local modules_dirs = resolve_modules_dirs(opts, install_root)
+    if #modules_dirs == 0 then
         return {
             ok = false, conflicts = {}, warnings = {},
             errors = {{
                 lib_id = "<module>", kind = "config",
-                message = "no install_root for ensure_for_module",
+                message = "no modules_dir candidates for ensure_for_module: " ..
+                          "pass opts.modules_dir, set SPOREL_MODULES_DIR / " ..
+                          "SPOREL_INSTALL_ROOT, or run under an engine " ..
+                          "providing engine.modules_dirs() / engine.install_root()",
             }},
             closure = {},
         }
     end
-    local path = install_root .. "/modules/" .. module_id
-        .. "/manifest.module"
-    opts.install_root = install_root
+    -- Find the first candidate that actually has this module.
+    local path = first_existing(modules_dirs,
+        module_id .. "/manifest.module")
+    if not path then
+        return {
+            ok = false, conflicts = {}, warnings = {},
+            errors = {{
+                lib_id = "<module>", kind = "manifest-read",
+                message = "module '" .. module_id ..
+                          "' manifest not found in any of " ..
+                          tostring(#modules_dirs) .. " candidate dirs",
+            }},
+            closure = {},
+        }
+    end
+    if install_root then opts.install_root = install_root end
     return M.ensure_for_module_at(path, opts)
 end
 

manifest.lib

@@ -1,8 +1,8 @@
 {
     "id": "lib-management.dep-fetcher",
-    "version": "0.1.0",
+    "version": "0.1.2",
     "api_min": "0.1",
     "deps": [
-        {"id": "lib-core.git", "version": "0.1.0"}
+        {"id": "lib-core.git", "version": "0.2.0"}
     ]
 }