contentbase 0.1.6 → 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.6",
+  "version": "0.2.0",
   "repository": "https://github.com/soederpop/contentbase",
   "website": "https://contentbase.soederpop.com",
   "type": "module",
@@ -50,6 +50,11 @@
     "vitest": "^1.6.0"
   },
   "luca": {
-    "aliases": ["contentbase", "content base", "content", "the orm"]
+    "aliases": [
+      "contentbase",
+      "content base",
+      "content",
+      "the orm"
+    ]
   }
 }

package/src/cli/commands/action.ts

@@ -38,6 +38,7 @@ async function handler(options: z.infer<typeof argsSchema>, context: { container
 
 commands.register('action', {
   description: 'Run a named action on the collection',
+  usage: '<name>',
   help: `# cnotes action
 
 Run a named action registered on the collection. Actions are custom functions defined in your collection's entry point.

package/src/cli/commands/create.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 import fs from 'fs/promises'
 import path from 'path'
 import matter from 'gray-matter'
+import { execSync } from 'child_process'
 import { commands } from '../registry.js'
 import { loadCollection } from '../load-collection.js'
 import { kebabCase } from '../../utils/inflect.js'
@@ -10,6 +11,7 @@ import { introspectMetaSchema } from '../../collection.js'
 const argsSchema = z.object({
   title: z.string().optional(),
   contentFolder: z.string().optional(),
+  openEditor: z.boolean().optional(),
 })
 
 async function handler(options: z.infer<typeof argsSchema>, context: { container: any }) {
@@ -125,10 +127,37 @@ async function handler(options: z.infer<typeof argsSchema>, context: { container
   await fs.writeFile(filePath, content, 'utf8')
 
   console.log(`Created ${filePath}`)
+
+  if (options.openEditor) {
+    const editor = process.env.EDITOR
+    if (editor) {
+      execSync(`${editor} ${filePath}`, { stdio: 'inherit' })
+    } else {
+      const candidates = ['cursor', 'code', 'vim']
+      let found = false
+      for (const cmd of candidates) {
+        try {
+          execSync(`which ${cmd}`, { stdio: 'ignore' })
+          execSync(`${cmd} ${filePath}`, { stdio: 'inherit' })
+          found = true
+          break
+        } catch {
+          // not available, try next
+        }
+      }
+      if (!found) {
+        console.error(
+          'No editor found. Tried: cursor, code, vim. Set $EDITOR to your preferred editor.'
+        )
+        process.exit(1)
+      }
+    }
+  }
 }
 
 commands.register('create', {
   description: 'Create a new document for a model type',
+  usage: '<model>',
   help: `# cnotes create
 
 Create a new document for a registered model, with proper frontmatter defaults and section scaffolding.
@@ -151,6 +180,7 @@ cnotes create <model> --title "Document Title" [options]
 |--------|-------------|
 | \`--title\` | **Required.** Title for the new document (used as H1 and slug) |
 | \`--meta.*\` | Set frontmatter fields (e.g. \`--meta.status active\`) |
+| \`--open-editor\` | Open the new file in your editor ($EDITOR, or tries cursor/code/vim) |
 | \`--contentFolder\` | Path to content folder |
 
 ## Template Lookup

package/src/cli/commands/extract.ts

@@ -123,6 +123,7 @@ async function handler(options: z.infer<typeof argsSchema>, context: { container
 
 commands.register('extract', {
   description: 'Extract specific sections from documents',
+  usage: '<glob>',
   help: `# cnotes extract
 
 Extract specific sections from one or more documents. Supports glob patterns for matching multiple documents and outputs clean markdown with normalized headings.

package/src/cli/commands/help.ts

@@ -22,7 +22,8 @@ async function handler(_options: any, context: { container: any }) {
 
   for (const name of commands.available) {
     const def = commands.get(name)!
-    lines.push(`| \`${name}\` | ${def.description} |`)
+    const label = def.usage ? `${name} ${def.usage}` : name
+    lines.push(`| \`${label}\` | ${def.description} |`)
   }
 
   lines.push(

package/src/cli/commands/init.ts

@@ -60,6 +60,7 @@ collection.register(Post);
 
 commands.register('init', {
   description: 'Initialize a new contentbase project',
+  usage: '[name]',
   help: `# cnotes init
 
 Scaffold a new contentbase project with a sample model and document.

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) {
@@ -223,6 +230,7 @@ async function handler(options: z.infer<typeof argsSchema>, { container }: { con
 
 commands.register('search', {
   description: 'Semantic search across collection documents',
+  usage: '<query>',
   help: `# cnotes search
 
 Search documents in the collection using keyword, semantic, or hybrid search modes. Requires a search index — run \`cnotes embed\` first.

package/src/cli/commands/text-search.ts

@@ -86,6 +86,7 @@ async function handler(options: z.infer<typeof argsSchema>, { container }: { con
 
 commands.register('text-search', {
   description: 'Search file contents with pattern matching',
+  usage: '<pattern>',
   help: `# cnotes text-search
 
 Search file contents within the collection using ripgrep. Returns matching files by default, or line-level detail with \`--expanded\`.

package/src/cli/commands/validate.ts

@@ -85,6 +85,7 @@ async function handler(options: z.infer<typeof argsSchema>, context: { container
 
 commands.register('validate', {
   description: 'Validate documents against their model schemas',
+  usage: '[model]',
   help: `# cnotes validate
 
 Validate documents against their model schemas. Check frontmatter types, required fields, and optionally fill in missing defaults.

package/src/cli/registry.ts

@@ -2,6 +2,7 @@ import type { z } from 'zod'
 
 export interface CommandDefinition {
   description: string
+  usage?: string
   help?: string
   argsSchema?: z.ZodType<any>
   handler: (options: any, context: { container: any }) => Promise<void>

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));
       }
     }