@gmickel/gno 0.16.0 → 0.17.0

package/src/serve/routes/api.ts

@@ -6,7 +6,12 @@
  */
 
 import type { Config, ModelPreset } from "../../config/types";
-import type { AskResult, Citation, SearchOptions } from "../../pipeline/types";
+import type {
+  AskResult,
+  Citation,
+  QueryModeInput,
+  SearchOptions,
+} from "../../pipeline/types";
 import type { SqliteAdapter } from "../../store/sqlite/adapter";
 import type { EmbedScheduler } from "../embed-scheduler";
 
@@ -61,6 +66,11 @@ export interface SearchRequestBody {
   limit?: number;
   minScore?: number;
   collection?: string;
+  since?: string;
+  until?: string;
+  /** Comma-separated category filters */
+  category?: string;
+  author?: string;
   /** Comma-separated tags - filter to docs having ALL (AND) */
   tagsAll?: string;
   /** Comma-separated tags - filter to docs having ANY (OR) */
@@ -73,6 +83,12 @@ export interface QueryRequestBody {
   minScore?: number;
   collection?: string;
   lang?: string;
+  since?: string;
+  until?: string;
+  /** Comma-separated category filters */
+  category?: string;
+  author?: string;
+  queryModes?: QueryModeInput[];
   noExpand?: boolean;
   noRerank?: boolean;
   /** Comma-separated tags - filter to docs having ALL (AND) */
@@ -86,6 +102,11 @@ export interface AskRequestBody {
   limit?: number;
   collection?: string;
   lang?: string;
+  since?: string;
+  until?: string;
+  /** Comma-separated category filters */
+  category?: string;
+  author?: string;
   maxAnswerTokens?: number;
   noExpand?: boolean;
   noRerank?: boolean;
@@ -137,6 +158,17 @@ function errorResponse(code: string, message: string, status = 400): Response {
   return jsonResponse({ error: { code, message } }, status);
 }
 
+function parseCommaSeparatedValues(input: string): string[] {
+  return Array.from(
+    new Set(
+      input
+        .split(",")
+        .map((value) => value.trim().toLowerCase())
+        .filter(Boolean)
+    )
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Route Handlers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -431,6 +463,12 @@ export async function handleDocs(
   url: URL
 ): Promise<Response> {
   const collection = url.searchParams.get("collection") || undefined;
+  const sortFieldRaw = (url.searchParams.get("sortField") ?? "modified")
+    .trim()
+    .toLowerCase();
+  const sortOrderRaw = (url.searchParams.get("sortOrder") ?? "desc")
+    .trim()
+    .toLowerCase();
 
   // Validate limit: positive integer, max 100
   const limitParam = Number(url.searchParams.get("limit"));
@@ -452,6 +490,18 @@ export async function handleDocs(
   }
   const offset = offsetParam || 0;
 
+  if (sortFieldRaw !== "modified" && !/^[a-z0-9_]+$/.test(sortFieldRaw)) {
+    return errorResponse(
+      "VALIDATION",
+      "sortField must be 'modified' or a lowercase frontmatter date key"
+    );
+  }
+
+  if (sortOrderRaw !== "asc" && sortOrderRaw !== "desc") {
+    return errorResponse("VALIDATION", "sortOrder must be 'asc' or 'desc'");
+  }
+  const sortOrder: "asc" | "desc" = sortOrderRaw === "asc" ? "asc" : "desc";
+
   // Parse tag filters
   let tagsAll: string[] | undefined;
   let tagsAny: string[] | undefined;
@@ -480,12 +530,30 @@ export async function handleDocs(
     }
   }
 
+  const dateFieldsResult = await store.getCollectionDateFields(collection);
+  if (!dateFieldsResult.ok) {
+    return errorResponse("RUNTIME", dateFieldsResult.error.message, 500);
+  }
+  const availableDateFields = dateFieldsResult.value;
+
+  if (
+    sortFieldRaw !== "modified" &&
+    !availableDateFields.includes(sortFieldRaw)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      `Unknown sortField: ${sortFieldRaw} for current collection`
+    );
+  }
+
   const result = await store.listDocumentsPaginated({
     collection,
     limit,
     offset,
     tagsAll,
     tagsAny,
+    sortField: sortFieldRaw,
+    sortOrder,
   });
 
   if (!result.ok) {
@@ -508,6 +576,9 @@ export async function handleDocs(
     total,
     limit,
     offset,
+    availableDateFields,
+    sortField: sortFieldRaw,
+    sortOrder,
   });
 }
 
@@ -1016,6 +1087,22 @@ export async function handleSearch(
     );
   }
 
+  if (body.since !== undefined && typeof body.since !== "string") {
+    return errorResponse("VALIDATION", "since must be a string");
+  }
+  if (body.until !== undefined && typeof body.until !== "string") {
+    return errorResponse("VALIDATION", "until must be a string");
+  }
+  if (body.category !== undefined && typeof body.category !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "category must be a comma-separated string"
+    );
+  }
+  if (body.author !== undefined && typeof body.author !== "string") {
+    return errorResponse("VALIDATION", "author must be a string");
+  }
+
   // Parse tag filters
   let tagsAll: string[] | undefined;
   let tagsAny: string[] | undefined;
@@ -1042,6 +1129,11 @@ export async function handleSearch(
     }
   }
 
+  const categories = body.category
+    ? parseCommaSeparatedValues(body.category)
+    : undefined;
+  const author = body.author?.trim() || undefined;
+
   // Only BM25 supported in web UI (vector/hybrid require LLM ports)
   const options: SearchOptions = {
     limit: Math.min(body.limit || 10, 50),
@@ -1049,6 +1141,10 @@ export async function handleSearch(
     collection: body.collection,
     tagsAll,
     tagsAny,
+    since: body.since,
+    until: body.until,
+    categories,
+    author,
   };
 
   const result = await searchBm25(store, query, options);
@@ -1062,7 +1158,7 @@ export async function handleSearch(
 
 /**
  * POST /api/query
- * Body: { query, limit?, minScore?, collection?, lang?, noExpand?, noRerank? }
+ * Body: { query, limit?, minScore?, collection?, lang?, queryModes?, noExpand?, noRerank? }
  * Returns hybrid search results (BM25 + vector + expansion + reranking).
  */
 export async function handleQuery(
@@ -1106,6 +1202,72 @@ export async function handleQuery(
     );
   }
 
+  if (body.since !== undefined && typeof body.since !== "string") {
+    return errorResponse("VALIDATION", "since must be a string");
+  }
+  if (body.until !== undefined && typeof body.until !== "string") {
+    return errorResponse("VALIDATION", "until must be a string");
+  }
+  if (body.category !== undefined && typeof body.category !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "category must be a comma-separated string"
+    );
+  }
+  if (body.author !== undefined && typeof body.author !== "string") {
+    return errorResponse("VALIDATION", "author must be a string");
+  }
+
+  // Validate queryModes
+  let queryModes: QueryModeInput[] | undefined;
+  if (body.queryModes !== undefined) {
+    if (!Array.isArray(body.queryModes)) {
+      return errorResponse(
+        "VALIDATION",
+        "queryModes must be an array of { mode, text } objects"
+      );
+    }
+
+    queryModes = [];
+    let hydeCount = 0;
+
+    for (const [index, entry] of body.queryModes.entries()) {
+      if (!entry || typeof entry !== "object") {
+        return errorResponse(
+          "VALIDATION",
+          `queryModes[${index}] must be an object`
+        );
+      }
+
+      const mode = (entry as { mode?: unknown }).mode;
+      const text = (entry as { text?: unknown }).text;
+      if (mode !== "term" && mode !== "intent" && mode !== "hyde") {
+        return errorResponse(
+          "VALIDATION",
+          `queryModes[${index}].mode must be one of: term, intent, hyde`
+        );
+      }
+      if (typeof text !== "string" || !text.trim()) {
+        return errorResponse(
+          "VALIDATION",
+          `queryModes[${index}].text must be a non-empty string`
+        );
+      }
+
+      if (mode === "hyde") {
+        hydeCount += 1;
+        if (hydeCount > 1) {
+          return errorResponse(
+            "VALIDATION",
+            "Only one hyde mode is allowed in queryModes"
+          );
+        }
+      }
+
+      queryModes.push({ mode, text: text.trim() });
+    }
+  }
+
   // Parse tag filters
   let tagsAll: string[] | undefined;
   let tagsAny: string[] | undefined;
@@ -1132,6 +1294,11 @@ export async function handleQuery(
     }
   }
 
+  const categories = body.category
+    ? parseCommaSeparatedValues(body.category)
+    : undefined;
+  const author = body.author?.trim() || undefined;
+
   const result = await searchHybrid(
     {
       store: ctx.store,
@@ -1147,10 +1314,15 @@ export async function handleQuery(
       minScore: body.minScore,
       collection: body.collection,
       lang: body.lang,
+      queryModes,
       noExpand: body.noExpand,
       noRerank: body.noRerank,
       tagsAll,
       tagsAny,
+      since: body.since,
+      until: body.until,
+      categories,
+      author,
     }
   );
 
@@ -1199,6 +1371,22 @@ export async function handleAsk(
   let tagsAll: string[] | undefined;
   let tagsAny: string[] | undefined;
 
+  if (body.since !== undefined && typeof body.since !== "string") {
+    return errorResponse("VALIDATION", "since must be a string");
+  }
+  if (body.until !== undefined && typeof body.until !== "string") {
+    return errorResponse("VALIDATION", "until must be a string");
+  }
+  if (body.category !== undefined && typeof body.category !== "string") {
+    return errorResponse(
+      "VALIDATION",
+      "category must be a comma-separated string"
+    );
+  }
+  if (body.author !== undefined && typeof body.author !== "string") {
+    return errorResponse("VALIDATION", "author must be a string");
+  }
+
   if (body.tagsAll) {
     try {
       tagsAll = parseAndValidateTagFilter(body.tagsAll);
@@ -1221,6 +1409,11 @@ export async function handleAsk(
     }
   }
 
+  const categories = body.category
+    ? parseCommaSeparatedValues(body.category)
+    : undefined;
+  const author = body.author?.trim() || undefined;
+
   const limit = Math.min(body.limit ?? 5, 20);
 
   // Run hybrid search first
@@ -1242,6 +1435,10 @@ export async function handleAsk(
       noRerank: body.noRerank,
       tagsAll,
       tagsAny,
+      since: body.since,
+      until: body.until,
+      categories,
+      author,
     }
   );
 
@@ -1254,6 +1451,7 @@ export async function handleAsk(
   // Generate grounded answer (requires genPort)
   let answer: string | undefined;
   let citations: Citation[] | undefined;
+  let answerContext: AskResult["meta"]["answerContext"] | undefined;
   let answerGenerated = false;
 
   if (ctx.genPort) {
@@ -1269,6 +1467,7 @@ export async function handleAsk(
       const processed = processAnswerResult(rawResult);
       answer = processed.answer;
       citations = processed.citations;
+      answerContext = processed.answerContext;
       answerGenerated = true;
     }
   }
@@ -1286,6 +1485,7 @@ export async function handleAsk(
       vectorsUsed: searchResult.value.meta.vectorsUsed ?? false,
       answerGenerated,
       totalResults: results.length,
+      answerContext,
     },
   };
 

package/src/store/migrations/006-document-metadata.ts

@@ -0,0 +1,104 @@
+/**
+ * Migration: document metadata fields for temporal/category/author filtering.
+ *
+ * @module src/store/migrations/006-document-metadata
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+const TABLE_INFO_DOCUMENTS = "PRAGMA table_info(documents)";
+
+interface TableInfoRow {
+  name: string;
+}
+
+function getDocumentColumns(db: Database): Set<string> {
+  const rows = db.query<TableInfoRow, []>(TABLE_INFO_DOCUMENTS).all();
+  return new Set(rows.map((row) => row.name));
+}
+
+function addColumnIfMissing(
+  db: Database,
+  columns: Set<string>,
+  column: string,
+  ddl: string
+): void {
+  if (columns.has(column)) {
+    return;
+  }
+
+  db.exec(ddl);
+  columns.add(column);
+}
+
+export const migration: Migration = {
+  version: 6,
+  name: "document_metadata",
+
+  up(db): void {
+    const columns = getDocumentColumns(db);
+
+    addColumnIfMissing(
+      db,
+      columns,
+      "source_ctime",
+      "ALTER TABLE documents ADD COLUMN source_ctime TEXT"
+    );
+    // SQLite rejects non-constant defaults in ALTER TABLE on older engines.
+    addColumnIfMissing(
+      db,
+      columns,
+      "indexed_at",
+      "ALTER TABLE documents ADD COLUMN indexed_at TEXT"
+    );
+    addColumnIfMissing(
+      db,
+      columns,
+      "content_type",
+      "ALTER TABLE documents ADD COLUMN content_type TEXT"
+    );
+    addColumnIfMissing(
+      db,
+      columns,
+      "categories",
+      "ALTER TABLE documents ADD COLUMN categories TEXT"
+    );
+    addColumnIfMissing(
+      db,
+      columns,
+      "author",
+      "ALTER TABLE documents ADD COLUMN author TEXT"
+    );
+    addColumnIfMissing(
+      db,
+      columns,
+      "frontmatter_date",
+      "ALTER TABLE documents ADD COLUMN frontmatter_date TEXT"
+    );
+
+    db.exec(`
+      UPDATE documents
+      SET indexed_at = datetime('now')
+      WHERE indexed_at IS NULL
+    `);
+
+    db.exec(
+      "CREATE INDEX IF NOT EXISTS idx_documents_source_mtime ON documents(source_mtime)"
+    );
+    db.exec(
+      "CREATE INDEX IF NOT EXISTS idx_documents_content_type ON documents(content_type)"
+    );
+    db.exec(
+      "CREATE INDEX IF NOT EXISTS idx_documents_author ON documents(author)"
+    );
+  },
+
+  down(db): void {
+    db.exec("DROP INDEX IF EXISTS idx_documents_author");
+    db.exec("DROP INDEX IF EXISTS idx_documents_content_type");
+    db.exec("DROP INDEX IF EXISTS idx_documents_source_mtime");
+    // SQLite cannot drop columns without table rebuild; keep columns on rollback.
+  },
+};

package/src/store/migrations/007-document-date-fields.ts

@@ -0,0 +1,24 @@
+/**
+ * Migration: document frontmatter date field map.
+ *
+ * @module src/store/migrations/007-document-date-fields
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 7,
+  name: "document_date_fields",
+
+  up(db: Database): void {
+    db.exec(`
+      ALTER TABLE documents ADD COLUMN date_fields TEXT
+    `);
+  },
+
+  down(): void {
+    // SQLite cannot drop columns without table rebuild; keep column on rollback.
+  },
+};

package/src/store/migrations/index.ts

@@ -19,6 +19,8 @@ import { migration as m002 } from "./002-documents-fts";
 import { migration as m003 } from "./003-doc-tags";
 import { migration as m004 } from "./004-doc-links";
 import { migration as m005 } from "./005-graph-indexes";
+import { migration as m006 } from "./006-document-metadata";
+import { migration as m007 } from "./007-document-date-fields";
 
 /** All migrations in order */
-export const migrations = [m001, m002, m003, m004, m005];
+export const migrations = [m001, m002, m003, m004, m005, m006, m007];