fix: sanitize FTS5 search queries to handle special characters

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: danielkov

.boop/changelogs/patch-01khv1ya5cxbd9av0mznpv3pe9.md

@@ -0,0 +1,7 @@
+### FTS5 search no longer fails on special characters
+
+Queries containing FTS5 operator characters like `-`, `+`, `*`, or keywords like `NOT`/`OR`/`AND` are now properly escaped before being passed to SQLite's FTS5 `MATCH` clause.
+
+Previously, running something like `granary plan "Fix TypeScript v2 build failures - 11 root causes from SDK battery tests"` would fail because the `-` was interpreted as FTS5's NOT operator. Now, each token is individually quoted and purely-punctuation tokens (like a bare `-`) are dropped, so the search works regardless of what characters appear in the plan name.
+
+Search queries also now use `OR` semantics instead of implicit `AND`, which makes prior-art matching more lenient — a project only needs to match *some* of the query terms to appear in results, rather than requiring all of them.

src/cli/plan.rs

@@ -431,4 +431,34 @@ mod tests {
             "prior art should be empty when the only match is excluded"
         );
     }
+
+    #[tokio::test]
+    async fn test_find_prior_art_with_special_characters() {
+        let (pool, _temp) = setup_test_db().await;
+
+        let project = services::create_project(
+            &pool,
+            CreateProject {
+                name: "TypeScript SDK battery tests".to_string(),
+                ..Default::default()
+            },
+        )
+        .await
+        .unwrap();
+
+        // Query contains `-` which is an FTS5 NOT operator when unescaped
+        let results = find_prior_art(
+            &pool,
+            "Fix TypeScript v2 build failures - 11 root causes from SDK battery tests",
+            "nonexistent-id",
+        )
+        .await
+        .unwrap();
+
+        let result_ids: Vec<&str> = results.iter().map(|r| r.project.id.as_str()).collect();
+        assert!(
+            result_ids.contains(&project.id.as_str()),
+            "search with special characters should still find matching projects"
+        );
+    }
 }

src/db/mod.rs

@@ -1852,8 +1852,27 @@ pub mod search {
         pub rank: f64,
     }
 
+    /// Sanitize a user query for FTS5 by individually quoting each token
+    /// and joining them with OR for lenient matching.
+    /// This prevents FTS5 operators (`-`, `+`, `*`, `NOT`, `OR`, `AND`, `NEAR`)
+    /// from being interpreted as query syntax, and ensures queries with many
+    /// terms still return results when only some terms match.
+    fn sanitize_fts5_query(query: &str) -> String {
+        query
+            .split_whitespace()
+            .filter(|token| token.chars().any(|c| c.is_alphanumeric()))
+            .map(|token| {
+                // Escape any double quotes inside the token, then wrap in quotes
+                let escaped = token.replace('"', "\"\"");
+                format!("\"{escaped}\"")
+            })
+            .collect::<Vec<_>>()
+            .join(" OR ")
+    }
+
     /// Search all entity types using FTS5 full-text search with BM25 ranking
     pub async fn search_all(pool: &SqlitePool, query: &str, limit: i32) -> Result<Vec<FtsMatch>> {
+        let sanitized = sanitize_fts5_query(query);
         let rows = sqlx::query_as::<_, FtsMatch>(
             r#"
             SELECT entity_type, entity_id, rank
@@ -1863,7 +1882,7 @@ pub mod search {
             LIMIT ?
             "#,
         )
-        .bind(query)
+        .bind(&sanitized)
         .bind(limit)
         .fetch_all(pool)
         .await?;
@@ -1872,6 +1891,7 @@ pub mod search {
 
     /// Search projects using FTS5 full-text search
     pub async fn search_projects(pool: &SqlitePool, query: &str) -> Result<Vec<Project>> {
+        let sanitized = sanitize_fts5_query(query);
         let ids = sqlx::query_scalar::<_, String>(
             r#"
             SELECT entity_id
@@ -1881,7 +1901,7 @@ pub mod search {
             LIMIT 50
             "#,
         )
-        .bind(query)
+        .bind(&sanitized)
         .fetch_all(pool)
         .await?;
 
@@ -1901,6 +1921,7 @@ pub mod search {
 
     /// Search tasks using FTS5 full-text search
     pub async fn search_tasks(pool: &SqlitePool, query: &str) -> Result<Vec<Task>> {
+        let sanitized = sanitize_fts5_query(query);
         let ids = sqlx::query_scalar::<_, String>(
             r#"
             SELECT entity_id
@@ -1910,7 +1931,7 @@ pub mod search {
             LIMIT 50
             "#,
         )
-        .bind(query)
+        .bind(&sanitized)
         .fetch_all(pool)
         .await?;
 
@@ -1933,6 +1954,7 @@ pub mod search {
         pool: &SqlitePool,
         query: &str,
     ) -> Result<Vec<crate::models::Initiative>> {
+        let sanitized = sanitize_fts5_query(query);
         let ids = sqlx::query_scalar::<_, String>(
             r#"
             SELECT entity_id
@@ -1942,7 +1964,7 @@ pub mod search {
             LIMIT 50
             "#,
         )
-        .bind(query)
+        .bind(&sanitized)
         .fetch_all(pool)
         .await?;
 
@@ -1959,6 +1981,52 @@ pub mod search {
         .await?;
         Ok(initiatives)
     }
+
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+
+        #[test]
+        fn sanitize_plain_words() {
+            assert_eq!(sanitize_fts5_query("hello world"), r#""hello" OR "world""#);
+        }
+
+        #[test]
+        fn sanitize_dash_operator() {
+            // The bare `-` is dropped (no alphanumeric chars)
+            assert_eq!(
+                sanitize_fts5_query("Fix TypeScript v2 build failures - 11 root causes"),
+                r#""Fix" OR "TypeScript" OR "v2" OR "build" OR "failures" OR "11" OR "root" OR "causes""#
+            );
+        }
+
+        #[test]
+        fn sanitize_embedded_quotes() {
+            assert_eq!(
+                sanitize_fts5_query(r#"say "hello""#),
+                "\"say\" OR \"\"\"hello\"\"\"",
+            );
+        }
+
+        #[test]
+        fn sanitize_empty_query() {
+            assert_eq!(sanitize_fts5_query(""), "");
+        }
+
+        #[test]
+        fn sanitize_single_word() {
+            assert_eq!(sanitize_fts5_query("auth"), r#""auth""#);
+        }
+
+        #[test]
+        fn sanitize_various_operators() {
+            // NOT, OR, AND are FTS5 operators — quoting neutralises them
+            assert_eq!(
+                sanitize_fts5_query("NOT this OR that"),
+                r#""NOT" OR "this" OR "OR" OR "that""#
+            );
+        }
+    }
 }
 
 /// Database operations for getting next tasks across an initiative