feat(http): migrate read path to adapter layer (#261) (#289)

* feat(http): migrate read path to adapter layer (#261)

Spec #258 isolated markdown internals (SpecLoader, SpecInfo, SpecWriter,
SpecArchiver, …) behind a module boundary and left leanspec-http
intentionally broken as a compiler-guided migration map. This change
implements the read-path portion of that migration per spec #261:

- types/specs.rs: SpecSummary/SpecDetail now build from &SpecDoc using
  schema semantic hints (status, priority, tags, assignee) rather than
  the old SpecInfo frontmatter struct.
- handlers/specs/helpers.rs: get_loader_and_project replaced with
  get_adapter_and_project returning Box<dyn Adapter>, plus shared
  helpers for AdapterError → HTTP mapping and a markdown-adapter guard.
- handlers/specs/read.rs: list / get / search / raw / sub-spec read
  handlers go through adapter.list() and adapter.get(). Hierarchy and
  required_by are computed from SpecDoc.links instead of the markdown
  loader's relationship index.
- handlers/specs/compute.rs: stats group by semantic-hint fields on
  SpecDoc; dependencies and per-spec validation now return HTTP 422
  with a clear error when the active adapter is not markdown.
- watcher.rs / state.rs: the file watcher holds a typed
  Arc<MarkdownAdapter> per project for cache invalidation and only
  activates for projects whose adapter resolves to markdown.
- handlers/adapter.rs: adds GET /api/projects/{id}/schema returning
  the active adapter's SpecSchema as JSON so the UI can render dynamic
  field sets.

Write handlers (create / metadata / raw / checklist / batch) are
migrated minimally to the adapter API so the crate compiles — they
keep using leanspec_core::adapters::markdown::{SpecInfo, SpecStatus,
SpecFrontmatter} via the public markdown module path for transition
checks, umbrella completion verification, and template rendering.
Full fetch-transform-push migration of those handlers lives in #262.

Tests: cargo test -p leanspec-http (102 passing), cargo clippy
-p leanspec-http -- -D warnings, cargo fmt -- --check all green.

Closes #261

* fix(http): address review feedback on adapter migration

Copilot review on #289 flagged seven issues; the substantive ones are fixed
here:

* Path traversal in `resolve_markdown_spec_path`: spec ids containing `..`,
  path separators, or absolute paths now return None instead of joining
  outside the specs root. Same `invalid_spec_id` guard rejects malicious
  names in `create_project_spec` so they can't write outside `specs_dir`.
* `file_path` regression on markdown list/search responses: SpecDoc.url is
  None for the markdown adapter, so list summaries had empty `file_path`.
  A new `populate_file_path` helper falls back to the on-disk README path
  for markdown projects so the field round-trips like before.
* Cycle detection in `build_hierarchy`: parent links forming a cycle (A→B,
  B→A) would recurse forever. The walker now carries a visited set and
  short-circuits when a spec is re-entered, so a malformed dataset can no
  longer stack-overflow the server.
* Relative `settings.directory` resolution: a markdown adapter config with
  `directory: specs` was being resolved against the server CWD rather than
  the project root. New `adapter_resolution.rs` module normalises relative
  paths against `project_root` before instantiating the adapter, so the
  `/specs`, `/adapter`, and `/schema` endpoints all agree on the right
  spec tree.
* Duplicated adapter config candidate list: `state.rs` had its own copy of
  the YAML candidate paths. Both watcher and handlers now share
  `adapter_resolution::ADAPTER_CONFIG_CANDIDATES`/`find_adapter_config`,
  so watcher activation can't drift from request-time resolution.
* Fuzzy spec id match in `resolve_markdown_spec_path`: the old `contains`
  heuristic would resolve `01` onto `001-foo` or `foo` onto `bar-foo-baz`.
  Tightened to numeric-prefix or slug-suffix exact match against the
  directory's `<NNN>-<slug>` shape.

Added unit tests cover: `invalid_spec_id` rejecting traversal, fuzzy
matching boundaries, `build_hierarchy` terminating on a parent cycle, and
the new adapter-resolution behaviour (fallback, relative→absolute,
absolute preserved, non-markdown left alone).

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: tikazyq

rust/leanspec-http/src/adapter_resolution.rs

@@ -0,0 +1,166 @@
+//! Shared helpers for resolving the active adapter for a project.
+//!
+//! Centralised so handlers (`/specs`, `/adapter`, `/schema`) and the file
+//! watcher in `state.rs` all use the exact same lookup order and config
+//! normalisation. Keeping this in one place stops watcher activation from
+//! drifting away from request-time adapter resolution.
+
+use std::path::{Path, PathBuf};
+
+use leanspec_core::adapters::{Adapter, AdapterConfig, AdapterError, AdapterRegistry};
+
+/// Candidate file paths (relative to the project root) for adapter config,
+/// in priority order. The legacy `provider:` files are honoured so existing
+/// projects keep working.
+pub const ADAPTER_CONFIG_CANDIDATES: &[&str] = &[
+    "leanspec.adapter.yaml",
+    ".lean-spec/adapter.yaml",
+    "leanspec.provider.yaml",
+    ".lean-spec/provider.yaml",
+];
+
+/// Returns the first adapter config file that exists under `project_root`.
+pub fn find_adapter_config(project_root: &Path) -> Option<PathBuf> {
+    ADAPTER_CONFIG_CANDIDATES
+        .iter()
+        .map(|c| project_root.join(c))
+        .find(|p| p.exists())
+}
+
+/// Load the adapter config for a project. Falls back to a markdown adapter
+/// rooted at `specs_dir` when no config file is present.
+///
+/// When the loaded config is a markdown adapter with a relative
+/// `settings.directory`, the directory is resolved against `project_root` so
+/// the adapter reads from the right tree regardless of the server's CWD.
+pub fn load_adapter_config(
+    project_root: &Path,
+    specs_dir: &Path,
+) -> Result<AdapterConfig, AdapterError> {
+    let mut config = if let Some(path) = find_adapter_config(project_root) {
+        AdapterRegistry::load_config(&path)?
+    } else {
+        AdapterConfig {
+            adapter: "markdown".into(),
+            settings: serde_json::json!({ "directory": specs_dir.to_string_lossy().as_ref() }),
+        }
+    };
+
+    normalise_markdown_directory(&mut config, project_root, specs_dir);
+    Ok(config)
+}
+
+/// Resolve and instantiate the active adapter for a project.
+pub fn resolve_adapter(
+    project_root: &Path,
+    specs_dir: &Path,
+) -> Result<Box<dyn Adapter>, AdapterError> {
+    let config = load_adapter_config(project_root, specs_dir)?;
+    AdapterRegistry::create(&config)
+}
+
+/// When the active adapter is markdown, rewrite a relative `settings.directory`
+/// (e.g. `"specs"`) so it's anchored at the project root. Falls back to
+/// `specs_dir` when the config omits the field entirely.
+fn normalise_markdown_directory(config: &mut AdapterConfig, project_root: &Path, specs_dir: &Path) {
+    if config.adapter != "markdown" {
+        return;
+    }
+
+    let current = config
+        .settings
+        .get("directory")
+        .and_then(|v| v.as_str())
+        .map(PathBuf::from);
+
+    let resolved = match current {
+        Some(dir) if dir.is_absolute() => dir,
+        Some(dir) => project_root.join(dir),
+        None => specs_dir.to_path_buf(),
+    };
+
+    if let Some(obj) = config.settings.as_object_mut() {
+        obj.insert(
+            "directory".into(),
+            serde_json::Value::String(resolved.to_string_lossy().into_owned()),
+        );
+    } else {
+        config.settings = serde_json::json!({ "directory": resolved.to_string_lossy().as_ref() });
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use tempfile::TempDir;
+
+    #[test]
+    fn fallback_uses_specs_dir() {
+        let tmp = TempDir::new().unwrap();
+        let specs = tmp.path().join("specs");
+        fs::create_dir_all(&specs).unwrap();
+
+        let config = load_adapter_config(tmp.path(), &specs).unwrap();
+        assert_eq!(config.adapter, "markdown");
+        assert_eq!(
+            config.settings.get("directory").and_then(|v| v.as_str()),
+            Some(specs.to_string_lossy().as_ref())
+        );
+    }
+
+    #[test]
+    fn relative_directory_resolved_against_project_root() {
+        let tmp = TempDir::new().unwrap();
+        let project = tmp.path();
+        let yaml = project.join("leanspec.adapter.yaml");
+        fs::write(&yaml, "adapter: markdown\ndirectory: docs/specs\n").unwrap();
+
+        let specs = project.join("specs");
+        let config = load_adapter_config(project, &specs).unwrap();
+        let resolved = config
+            .settings
+            .get("directory")
+            .and_then(|v| v.as_str())
+            .unwrap();
+        assert_eq!(resolved, project.join("docs/specs").to_string_lossy());
+    }
+
+    #[test]
+    fn absolute_directory_preserved() {
+        let tmp = TempDir::new().unwrap();
+        let project = tmp.path();
+        let yaml = project.join("leanspec.adapter.yaml");
+        let abs = project.join("absolute-specs");
+        fs::write(
+            &yaml,
+            format!("adapter: markdown\ndirectory: {}\n", abs.display()),
+        )
+        .unwrap();
+
+        let specs = project.join("specs");
+        let config = load_adapter_config(project, &specs).unwrap();
+        assert_eq!(
+            config.settings.get("directory").and_then(|v| v.as_str()),
+            Some(abs.to_string_lossy().as_ref())
+        );
+    }
+
+    #[test]
+    fn non_markdown_adapter_left_alone() {
+        let tmp = TempDir::new().unwrap();
+        let project = tmp.path();
+        let yaml = project.join("leanspec.adapter.yaml");
+        fs::write(
+            &yaml,
+            "adapter: github\nowner: acme\nrepo: backend\ntoken_env: TEST_TOKEN\n",
+        )
+        .unwrap();
+
+        let specs = project.join("specs");
+        let config = load_adapter_config(project, &specs).unwrap();
+        assert_eq!(config.adapter, "github");
+        // No `directory` key was added.
+        assert!(config.settings.get("directory").is_none());
+    }
+}

rust/leanspec-http/src/handlers/adapter.rs

@@ -1,53 +1,22 @@
-//! Adapter introspection endpoint.
+//! Adapter introspection endpoints.
 //!
-//! Returns the active [`leanspec_core::Adapter`]'s capabilities for a given
-//! project so clients (UI, agents) can build adapter-aware workflows without
-//! assuming markdown-specific conventions.
+//! Surfaces the active [`leanspec_core::Adapter`]'s capabilities and schema
+//! for a given project so clients (UI, agents) can build adapter-aware
+//! workflows without assuming markdown-specific conventions.
 
 #![allow(clippy::result_large_err)]
 
-use std::path::Path as FsPath;
-
 use axum::extract::{Path, State};
 use axum::http::StatusCode;
 use axum::Json;
-use leanspec_core::adapters::{AdapterCapabilities, AdapterConfig, AdapterRegistry};
+use leanspec_core::adapters::AdapterCapabilities;
+use leanspec_core::SpecSchema;
 
+use crate::adapter_resolution::resolve_adapter;
 use crate::error::ApiError;
 use crate::state::AppState;
 use crate::utils::resolve_project;
 
-/// Candidate file paths (relative to the project root) for adapter config,
-/// in priority order. The legacy `provider:` files are honoured so existing
-/// projects keep working.
-const ADAPTER_CONFIG_CANDIDATES: &[&str] = &[
-    "leanspec.adapter.yaml",
-    ".lean-spec/adapter.yaml",
-    "leanspec.provider.yaml",
-    ".lean-spec/provider.yaml",
-];
-
-fn resolve_adapter_for_project(
-    project_root: &FsPath,
-    specs_dir: &FsPath,
-) -> Result<Box<dyn leanspec_core::Adapter>, (StatusCode, Json<ApiError>)> {
-    for candidate in ADAPTER_CONFIG_CANDIDATES {
-        let path = project_root.join(candidate);
-        if path.exists() {
-            let config = AdapterRegistry::load_config(&path).map_err(api_error)?;
-            return AdapterRegistry::create(&config).map_err(api_error);
-        }
-    }
-
-    // No adapter config — fall back to the markdown adapter pointed at the
-    // project's declared specs directory.
-    let config = AdapterConfig {
-        adapter: "markdown".into(),
-        settings: serde_json::json!({ "directory": specs_dir.to_string_lossy().as_ref() }),
-    };
-    AdapterRegistry::create(&config).map_err(api_error)
-}
-
 fn api_error(err: leanspec_core::AdapterError) -> (StatusCode, Json<ApiError>) {
     (
         StatusCode::INTERNAL_SERVER_ERROR,
@@ -61,6 +30,19 @@ pub async fn get_project_adapter_capabilities(
     Path(project_id): Path<String>,
 ) -> Result<Json<AdapterCapabilities>, (StatusCode, Json<ApiError>)> {
     let project = resolve_project(&state, &project_id).await?;
-    let adapter = resolve_adapter_for_project(&project.path, &project.specs_dir)?;
+    let adapter = resolve_adapter(&project.path, &project.specs_dir).map_err(api_error)?;
     Ok(Json(adapter.capabilities().clone()))
 }
+
+/// GET /api/projects/{id}/schema
+///
+/// Returns the active adapter's `SpecSchema` so the UI can render dynamic
+/// field sets without hard-coding adapter-specific conventions.
+pub async fn get_project_schema(
+    State(state): State<AppState>,
+    Path(project_id): Path<String>,
+) -> Result<Json<SpecSchema>, (StatusCode, Json<ApiError>)> {
+    let project = resolve_project(&state, &project_id).await?;
+    let adapter = resolve_adapter(&project.path, &project.specs_dir).map_err(api_error)?;
+    Ok(Json(adapter.schema().clone()))
+}