[gobby-#314] feat: add indexed grep and graph sync contract

Author: joshwilhelmi

CHANGELOG.md

@@ -9,6 +9,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.5] — gcode
+
+### Added
+
+#### gcode
+
+- **Indexed grep** — `gcode grep <pattern> [PATH ...]` now provides exact
+  line-oriented search over the indexed `code_content_chunks` corpus. It
+  supports `-i`, `-F`, `-C/-A/-B`, `-g/--glob`, and `-m/--max-count`, with text
+  output shaped like grep and JSON output that includes match spans, context,
+  scan counts, and truncation state.
+
+### Changed
+
+#### gcode
+
+- **Graph sync-file contract** — `gcode graph sync-file` now classifies missing
+  indexed projects and files from PostgreSQL before FalkorDB access. Human
+  defaults stay strict with typed JSON errors and exit code `2`, while daemon
+  and background-worker callers can use `--allow-missing-indexed-file` to turn
+  stale missing-file work into a skipped payload.
+
 ## [0.4.4] — gobby-hooks
 
 ### Added

Cargo.lock

@@ -27,7 +27,8 @@ This workspace contains four Gobby CLI tools plus a shared library:
 
 AST-aware code search powered by tree-sitter. Indexes 18 languages plus safe
 repo text files into the Gobby PostgreSQL hub, with pg_search BM25 for symbol
-lookup, repo-content search across source/docs/config/scripts, file tree
+lookup, exact indexed grep over repo content chunks, ranked repo-content search
+across source/docs/config/scripts, file tree
 navigation, and hybrid ranking. When FalkorDB, Qdrant, and an embeddings
 endpoint are configured - typically through Gobby - `gcode` adds graph-aware
 search, semantic search, optional graph expansion for exact symbol lookup

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "gobby-code"
-version = "0.9.4"
+version = "0.9.5"
 edition = "2024"
 rust-version = "1.88"
 authors = ["Josh Wilhelmi <hello@gobby.ai>"]
@@ -70,6 +70,7 @@ streaming-iterator = "0.1"
 
 # Utilities
 glob = "0.3"
+regex = "1"
 shlex = "1"
 sha2 = "0.10"
 uuid = { version = "1", features = ["v5"] }

crates/gcode/Cargo.toml

@@ -126,6 +126,8 @@ gcode search-symbol "outline" --kind function --language rust
 gcode search-symbol "Context" crates/gcode/src
 gcode search-text "query"                 # BM25 on symbol names/signatures
 gcode search-text "query" crates/gcode/src
+gcode grep "pattern"                      # Exact indexed content grep
+gcode grep "pattern" src -m 50            # Cap matching lines globally
 gcode search-content "query"              # BM25 on source, comments, skill files, docs/Markdown, configs, CSS, SQL, and extensionless text
 gcode search-content "query" docs/**/*.md crates/gcode/src
 
@@ -145,6 +147,7 @@ gcode blast-radius "handleAuth" --depth 3 # Transitive impact analysis
 # Graph lifecycle (requires FalkorDB)
 gcode graph clear                         # Clear current project's graph projection
 gcode graph clear --project-id <id>       # Clear graph projection by explicit project id
+gcode graph sync-file --file src/lib.rs   # Sync one indexed file into the graph projection
 gcode graph rebuild                       # Rebuild current project's graph projection
 
 # Project management
@@ -245,6 +248,9 @@ lifecycle depends on Qdrant plus embeddings for sync/rebuild. All code-index
 projection lifecycle paths are Rust-owned and scoped to code projection state:
 graph clears target code-index FalkorDB labels only, and vector clears target
 only `code_symbols_{project_id}` rather than memory vector collections.
+`gcode graph sync-file --allow-missing-indexed-file` is reserved for daemon and
+background-worker stale work; humans should let the default strict missing-file
+error surface stale or incorrect sync requests.
 
 ## Language Support
 

crates/gcode/README.md

@@ -16,9 +16,10 @@ This project is indexed. Use `gcode` via Bash for fast code search and navigatio
 - `gcode search "query" [PATH ...]` — hybrid search: pg_search BM25 + semantic + graph boost (best for fuzzy or natural-language queries)
 - `gcode search-symbol "name" [PATH ...]` — exact-first symbol lookup with deterministic ranking; add `--with-graph` to include FalkorDB graph neighbors when available
 - `gcode search-text "query" [PATH ...]` — pg_search BM25 search on symbol names, signatures, and docstrings
+- `gcode grep "pattern" [PATH ...]` — exact indexed content grep over `code_content_chunks`; use `gcode grep "pattern" src -m 50` to cap matching lines
 - `gcode search-content "query" [PATH ...]` — full-text search across repo text chunks: source, comments, docs/Markdown, skill files, configs, scripts, CSS, SQL, and extensionless text
 
-Search filters compose: `search` and `search-symbol` accept `--kind <kind>`; use `gcode kinds` to discover values. All search commands accept positional path filters after the query (paths or globs, OR semantics), plus `--language <lang>`, `--limit N`, and `--offset N` for scoped or paginated results. Hybrid JSON results include final display `score`, raw `rrf_score`, and deterministic `sources`; path globs that require post-filter fallback surface a hint/warning.
+Search filters compose: `search` and `search-symbol` accept `--kind <kind>`; use `gcode kinds` to discover values. Ranked search commands accept positional path filters after the query (paths or globs, OR semantics), plus `--language <lang>`, `--limit N`, and `--offset N` for scoped or paginated results. `gcode grep` accepts positional paths, `-g/--glob`, `-i`, `-F`, `-C/-A/-B`, and `-m/--max-count`; it rejects `--limit`. Hybrid JSON results include final display `score`, raw `rrf_score`, and deterministic `sources`; path globs that require post-filter fallback surface a hint/warning.
 
 ## Retrieval
 
@@ -32,7 +33,7 @@ Symbol IDs must be full stored UUIDs from `gcode search`, `gcode search-symbol`,
 
 When navigating code for context or understanding:
 
-1. **Locate with gcode**: `gcode search "concept"`, `gcode search-symbol "name"`, or `gcode search-content "text"` to find relevant hits.
+1. **Locate with gcode**: `gcode grep "exact string"` for exact line matches, `gcode search "concept"`, `gcode search-symbol "name"`, or `gcode search-content "text"` for ranked/fuzzy hits.
 2. **Survey file structure**: `gcode outline path/to/file` to see the symbol hierarchy without reading the whole file.
 3. **Retrieve exact code**: `gcode symbol <full-uuid>` or `gcode symbols <full-uuid> <full-uuid> ...` using IDs from search or outline.
 4. **Fetch tight neighboring context only when needed**: use `sed`/`awk` only for tight neighboring context (1-3 lines) after symbol retrieval.
@@ -64,6 +65,7 @@ Use `gcode` directly for the code-index graph projection via the Gobby daemon.
 for the UI, but graph sync/read/lifecycle behavior lives in `gcode`.
 
 - `gcode graph sync-file --file <file>` — sync one indexed file into the graph projection
+- `gcode graph sync-file --file <file> --allow-missing-indexed-file` — daemon/background-worker stale-work tolerance only
 - `gcode graph clear` — clear the current project's graph projection
 - `gcode graph clear --project-id <id>` — clear a projection without resolving a project root
 - `gcode graph rebuild` — rebuild it (cheaper than `gcode invalidate` + reindex; doesn't touch PostgreSQL symbol/content rows)
@@ -74,7 +76,8 @@ for the UI, but graph sync/read/lifecycle behavior lives in `gcode`.
 |---|---|
 | A function or class by concept (fuzzy) | `gcode search "concept"` |
 | A symbol you know the exact name of | `gcode search-symbol "name"` |
-| A string literal, doc phrase, config value, comment, script line, CSS rule | `gcode search-content "text"` |
+| An exact string literal, doc phrase, config value, comment, script line, CSS rule | `gcode grep "pattern" [PATH ...]` |
+| Ranked content search across comments/docs/config/source text | `gcode search-content "query" [PATH ...]` |
 | Structure of a file without reading it | `gcode outline path/to/file` |
 | Source code of a specific symbol | `gcode symbol <full-uuid>` |
 | What breaks if I change X | `gcode blast-radius <name>` |

crates/gcode/assets/SKILL.md

@@ -13,6 +13,66 @@ use serde_json::{Value, json};
 
 const GOBBY_HINT: &str =
     "Graph commands require FalkorDB, available with Gobby. See: https://github.com/GobbyAI/gobby";
+pub const GRAPH_SYNC_CONTRACT_EXIT_CODE: u8 = 2;
+
+#[derive(Debug)]
+pub struct GraphSyncContractError {
+    payload: Value,
+}
+
+impl GraphSyncContractError {
+    fn project_not_indexed(ctx: &Context, file_path: &str) -> Self {
+        Self {
+            payload: json!({
+                "success": false,
+                "project_id": ctx.project_id,
+                "file_path": file_path,
+                "status": "error",
+                "reason": "project_not_indexed",
+                "error": format!("project {} is not indexed", ctx.project_id),
+            }),
+        }
+    }
+
+    fn indexed_file_not_found(ctx: &Context, file_path: &str) -> Self {
+        Self {
+            payload: json!({
+                "success": false,
+                "project_id": ctx.project_id,
+                "file_path": file_path,
+                "status": "error",
+                "reason": "indexed_file_not_found",
+                "error": format!("indexed file `{file_path}` was not found for project {}", ctx.project_id),
+            }),
+        }
+    }
+
+    pub fn exit_code(&self) -> u8 {
+        GRAPH_SYNC_CONTRACT_EXIT_CODE
+    }
+
+    pub fn print(&self) -> anyhow::Result<()> {
+        output::print_json(&self.payload)
+    }
+
+    pub fn payload(&self) -> &Value {
+        &self.payload
+    }
+}
+
+impl std::fmt::Display for GraphSyncContractError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let reason = self
+            .payload
+            .get("reason")
+            .and_then(Value::as_str)
+            .unwrap_or("graph_sync_contract_error");
+        write!(f, "graph sync-file contract error: {reason}")
+    }
+}
+
+impl std::error::Error for GraphSyncContractError {}
+
 fn format_success_text(output: &GraphLifecycleOutput) -> String {
     format!(
         "{} for project {}: {}",
@@ -54,20 +114,46 @@ fn lifecycle_output(
     }
 }
 
-struct GraphFileSyncOutcome {
-    relationships_written: usize,
-    symbols_synced: usize,
+enum GraphFileSyncOutcome {
+    Synced {
+        relationships_written: usize,
+        symbols_synced: usize,
+    },
+    SkippedMissingIndexedFile,
 }
 
-fn sync_file_graph(ctx: &Context, file_path: &str) -> anyhow::Result<GraphFileSyncOutcome> {
-    code_graph::require_graph_reads(ctx)?;
+fn skipped_missing_indexed_file_payload(ctx: &Context, file_path: &str) -> Value {
+    json!({
+        "project_id": ctx.project_id,
+        "file_path": file_path,
+        "status": "skipped",
+        "reason": "indexed_file_not_found",
+    })
+}
+
+fn sync_file_graph(
+    ctx: &Context,
+    file_path: &str,
+    allow_missing_indexed_file: bool,
+) -> anyhow::Result<GraphFileSyncOutcome> {
     let mut conn = db::connect_readwrite(&ctx.database_url)?;
+    if !db::indexed_project_exists(&mut conn, &ctx.project_id)? {
+        return Err(GraphSyncContractError::project_not_indexed(ctx, file_path).into());
+    }
+    if !db::indexed_file_exists(&mut conn, &ctx.project_id, file_path)? {
+        if allow_missing_indexed_file {
+            return Ok(GraphFileSyncOutcome::SkippedMissingIndexedFile);
+        }
+        return Err(GraphSyncContractError::indexed_file_not_found(ctx, file_path).into());
+    }
+
+    code_graph::require_graph_reads(ctx)?;
     let facts = db::read_graph_file_facts(&mut conn, &ctx.project_id, file_path)?;
     if !db::mark_graph_sync_attempted(&mut conn, &ctx.project_id, file_path)? {
-        anyhow::bail!(
-            "indexed file `{file_path}` was not found for project {}",
-            ctx.project_id
-        );
+        if allow_missing_indexed_file {
+            return Ok(GraphFileSyncOutcome::SkippedMissingIndexedFile);
+        }
+        return Err(GraphSyncContractError::indexed_file_not_found(ctx, file_path).into());
     }
     let relationships_written = code_graph::sync_file_graph(
         ctx,
@@ -77,7 +163,7 @@ fn sync_file_graph(ctx: &Context, file_path: &str) -> anyhow::Result<GraphFileSy
         &facts.calls,
     )?;
     db::mark_graph_synced(&mut conn, &ctx.project_id, file_path)?;
-    Ok(GraphFileSyncOutcome {
+    Ok(GraphFileSyncOutcome::Synced {
         relationships_written,
         symbols_synced: facts.definitions.len(),
     })
@@ -186,10 +272,25 @@ pub fn rebuild(ctx: &Context, format: Format) -> anyhow::Result<()> {
     run_lifecycle_action(ctx, GraphLifecycleAction::Rebuild, format)
 }
 
-pub fn sync_file(ctx: &Context, file_path: &str, format: Format) -> anyhow::Result<()> {
-    let sync = sync_file_graph(ctx, file_path)?;
-    let relationships_written = sync.relationships_written;
-    let report = ProjectionSyncReport::ok(1, sync.symbols_synced);
+pub fn sync_file(
+    ctx: &Context,
+    file_path: &str,
+    allow_missing_indexed_file: bool,
+    format: Format,
+) -> anyhow::Result<()> {
+    let sync = sync_file_graph(ctx, file_path, allow_missing_indexed_file)?;
+    let GraphFileSyncOutcome::Synced {
+        relationships_written,
+        symbols_synced,
+    } = sync
+    else {
+        let payload = skipped_missing_indexed_file_payload(ctx, file_path);
+        return match format {
+            Format::Json => output::print_json(&payload),
+            Format::Text => output::print_json_compact(&payload),
+        };
+    };
+    let report = ProjectionSyncReport::ok(1, symbols_synced);
     let summary = format!("synced {relationships_written} graph relationships for {file_path}");
     let payload = json!({
         "success": true,
@@ -691,6 +792,37 @@ mod tests {
         assert!(!source.contains(&daemon_lifecycle));
     }
 
+    #[test]
+    fn missing_project_sync_error_has_typed_payload() {
+        let ctx = make_ctx_no_falkordb();
+        let error = GraphSyncContractError::project_not_indexed(&ctx, "src/lib.rs");
+
+        assert_eq!(error.exit_code(), GRAPH_SYNC_CONTRACT_EXIT_CODE);
+        assert_eq!(error.payload()["project_id"], "test-project");
+        assert_eq!(error.payload()["file_path"], "src/lib.rs");
+        assert_eq!(error.payload()["status"], "error");
+        assert_eq!(error.payload()["reason"], "project_not_indexed");
+    }
+
+    #[test]
+    fn missing_file_sync_error_and_skip_payloads_are_typed() {
+        let ctx = make_ctx_no_falkordb();
+        let error = GraphSyncContractError::indexed_file_not_found(&ctx, "src/missing.rs");
+        let skipped = skipped_missing_indexed_file_payload(&ctx, "src/missing.rs");
+
+        assert_eq!(error.exit_code(), GRAPH_SYNC_CONTRACT_EXIT_CODE);
+        assert_eq!(error.payload()["reason"], "indexed_file_not_found");
+        assert_eq!(
+            skipped,
+            json!({
+                "project_id": "test-project",
+                "file_path": "src/missing.rs",
+                "status": "skipped",
+                "reason": "indexed_file_not_found",
+            })
+        );
+    }
+
     #[test]
     fn test_build_lifecycle_url_clear_uses_project_id_query() {
         let url = code_graph::build_lifecycle_url(