contentbase 0.1.8 → 0.2.0

package/README.md

@@ -402,6 +402,96 @@ const result = await executeQueryDSL(collection, {
 
 ---
 
+## Semantic Search
+
+Contentbase includes built-in semantic search that combines vector embeddings, BM25 keyword ranking, and your content models' metadata — so you can ask natural-language questions and scope results to specific models and frontmatter values in the same query.
+
+### Setup
+
+Generate embeddings for your collection:
+
+```bash
+# Uses OpenAI embeddings by default (requires OPENAI_API_KEY)
+cnotes embed
+
+# Or use local embeddings (no API key needed — auto-installs node-llama-cpp)
+cnotes embed --local
+
+# Check index health
+cnotes embed --status
+```
+
+The index is stored in `.contentbase/search.sqlite`. Documents are split into chunks at H2 section boundaries and each chunk is embedded independently, so search results can point to specific sections within a document. Only changed documents are re-embedded on subsequent runs (tracked via content hashes).
+
+### Searching
+
+```bash
+# Hybrid search (default) — combines keyword + vector for best results
+cnotes search "authentication patterns"
+
+# Keyword-only (BM25 ranking) — fast, good for exact terms
+cnotes search "deploymentConfig" --mode keyword
+
+# Vector-only (semantic similarity) — understands meaning, not just words
+cnotes search "how do deployments work" --mode vector
+```
+
+### Combining Search with Model Metadata
+
+The real power is combining semantic understanding with your content models' structured metadata. The `--model` flag scopes results to a specific model, and `--where` filters on frontmatter fields — so your Zod schemas double as search facets:
+
+```bash
+# Find approved plans related to infrastructure
+cnotes search "infrastructure" --model Plan --where "status=approved"
+
+# Search only within epics that are in progress
+cnotes search "user onboarding" --model Epic --where "status=in-progress"
+
+# Combine model filtering with result limits
+cnotes search "auth" --model Story -n 5
+```
+
+This means the same schema you use for validation and querying also powers search filtering. A model with `status`, `priority`, or `category` in its meta schema automatically becomes filterable in search — no extra configuration.
+
+### Search Modes
+
+| Mode | Algorithm | Best for |
+|------|-----------|----------|
+| `hybrid` (default) | BM25 + vector cosine similarity | General-purpose queries |
+| `keyword` | BM25 full-text ranking | Exact terms, code identifiers, names |
+| `vector` | Embedding cosine similarity | Conceptual queries, "how does X work" |
+
+### CLI Reference
+
+```bash
+cnotes search <query> [options]
+  --mode hybrid|keyword|vector   Search mode (default: hybrid)
+  --model <name>                 Filter by content model
+  --where <filter>               Metadata filter, e.g. "status=approved"
+  -n <number>                    Max results (default: 10)
+  --json                         Output as JSON
+  --full                         Include full document content in output
+  --bootstrap                    Build index if missing, then search
+
+cnotes embed [options]
+  --force                        Re-embed everything (ignore content hashes)
+  --provider openai|local        Embedding provider (default: openai)
+  --status                       Show index health without embedding
+  --local                        Use local embeddings (auto-installs if needed)
+  --install-local                Only install node-llama-cpp, then exit
+```
+
+### REST API
+
+When running `cnotes serve`, search is also available over HTTP:
+
+```
+GET  /api/search?q=<query>&mode=hybrid&model=Epic&limit=10
+POST /api/search  { "query": "...", "mode": "hybrid", "model": "Epic", "where": { "status": "approved" } }
+```
+
+---
+
 ## Validation
 
 Every model instance can be validated against its Zod schemas:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contentbase",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "repository": "https://github.com/soederpop/contentbase",
   "website": "https://contentbase.soederpop.com",
   "type": "module",

package/src/cli/commands/search.ts

@@ -193,22 +193,29 @@ async function handler(options: z.infer<typeof argsSchema>, { container }: { con
     return
   }
 
-  const header = `| # | Score | Document | Match |`
-  const separator = `|---|-------|----------|-------|`
-  const rows = results.map((r: any, i: number) => {
-    const score = `${Math.round(r.score * 100)}%`
-    const doc = r.title || r.pathId
-    let match = ''
+  const colors = ui.colors
+  const cols = process.stdout.columns || 80
+  const pad = '   '
+  const maxSnippet = cols - pad.length - 2
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i]
+    const title = r.title || r.pathId
+    console.log(`${colors.dim(`${i + 1}.`)} ${colors.bold(title)}`)
+    let relPath = r.pathId
+    try { relPath = path.relative(process.cwd(), collection.document(r.pathId).path) } catch {}
+    console.log(`${pad}${colors.cyan(relPath)}`)
     if (r.snippet) {
-      const snippet = r.snippet.replace(/\n/g, ' ').replace(/\|/g, '\\|').substring(0, 80)
-      const section = r.matchedSection || ''
-      match = section ? `**${section}**: ${snippet}` : snippet
+      let snippet = r.snippet
+        .replace(/>>>/g, '').replace(/<<</g, '')
+        .replace(/\n/g, ' ').replace(/\s+/g, ' ')
+        .replace(/[`*_~\[\]]/g, '').trim()
+      if (r.matchedSection) snippet = `${r.matchedSection} — ${snippet}`
+      if (snippet.length > maxSnippet) snippet = snippet.substring(0, maxSnippet - 1) + '…'
+      console.log(`${pad}${colors.dim(snippet)}`)
     }
-    return `| ${i + 1} | ${score} | ${doc} | ${match} |`
-  })
-
-  const table = [header, separator, ...rows].join('\n')
-  ui.markdown(table)
+    if (i < results.length - 1) console.log()
+  }
 
   if (options.full) {
     for (const r of results) {

package/src/collection.ts

@@ -191,9 +191,17 @@ export class Collection {
   }
 
   get available(): string[] {
-    return Array.from(this.#items.keys()).filter(
-      (id) => !this.#isExcludedByModel(id)
-    );
+    return Array.from(this.#items.keys())
+      .filter((id) => !this.#isExcludedByModel(id))
+      .sort();
+  }
+
+  /**
+   * Match available pathIds against one or more glob patterns.
+   */
+  matchPaths(patterns: string | string[]): string[] {
+    const isMatch = picomatch(patterns);
+    return this.available.filter((id) => isMatch(id));
   }
 
   /**

package/src/relationships/has-many.ts

@@ -135,6 +135,8 @@ export class HasManyRelationship<
     // e.g. Project hasMany Plans → looks for meta.project on Plan documents.
     const fk = this.#definition.foreignKey || this.#inferForeignKey();
     const slug = this.#document.slug;
+    const parentPrefix = this.#document.id.split("/")[0];
+    const idSegment = this.#document.id.slice(parentPrefix.length + 1);
     const prefix = targetDef.prefix;
     const results: InferModelInstance<TTarget>[] = [];
 
@@ -147,7 +149,7 @@ export class HasManyRelationship<
         const patternMeta = matchPatterns(targetDef.pattern, pathId);
         if (patternMeta) fkValue = patternMeta[fk];
       }
-      if (fkValue === slug) {
+      if (fkValue === slug || fkValue === idSegment) {
         results.push(this.#factory(doc, targetDef, this.#collection));
       }
     }