@gmickel/gno 0.3.0

package/src/cli/commands/query.ts

@@ -0,0 +1,220 @@
+/**
+ * gno query command implementation.
+ * Hybrid search with expansion, fusion, and reranking.
+ *
+ * @module src/cli/commands/query
+ */
+
+import { LlmAdapter } from '../../llm/nodeLlamaCpp/adapter';
+import { getActivePreset } from '../../llm/registry';
+import type {
+  EmbeddingPort,
+  GenerationPort,
+  RerankPort,
+} from '../../llm/types';
+import { type HybridSearchDeps, searchHybrid } from '../../pipeline/hybrid';
+import type { HybridSearchOptions, SearchResults } from '../../pipeline/types';
+import {
+  createVectorIndexPort,
+  type VectorIndexPort,
+} from '../../store/vector';
+import { initStore } from './shared';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type QueryCommandOptions = HybridSearchOptions & {
+  /** Override config path */
+  configPath?: string;
+  /** Override embedding model */
+  embedModel?: string;
+  /** Override generation model */
+  genModel?: string;
+  /** Override rerank model */
+  rerankModel?: string;
+  /** Output as JSON */
+  json?: boolean;
+  /** Output as Markdown */
+  md?: boolean;
+  /** Output as CSV */
+  csv?: boolean;
+  /** Output as XML */
+  xml?: boolean;
+  /** Output files only */
+  files?: boolean;
+};
+
+export interface QueryFormatOptions {
+  format: 'terminal' | 'json' | 'files' | 'csv' | 'md' | 'xml';
+  full?: boolean;
+  lineNumbers?: boolean;
+}
+
+export type QueryResult =
+  | { success: true; data: SearchResults }
+  | { success: false; error: string };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Command Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Execute gno query command.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: CLI orchestration with multiple output formats
+export async function query(
+  queryText: string,
+  options: QueryCommandOptions = {}
+): Promise<QueryResult> {
+  const isStructured =
+    options.json || options.files || options.csv || options.xml;
+  const limit = options.limit ?? (isStructured ? 20 : 5);
+
+  const initResult = await initStore({
+    configPath: options.configPath,
+    collection: options.collection,
+  });
+
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+
+  const { store, config } = initResult;
+
+  let embedPort: EmbeddingPort | null = null;
+  let genPort: GenerationPort | null = null;
+  let rerankPort: RerankPort | null = null;
+
+  try {
+    const preset = getActivePreset(config);
+    const llm = new LlmAdapter(config);
+
+    // Create embedding port (for vector search)
+    const embedUri = options.embedModel ?? preset.embed;
+    const embedResult = await llm.createEmbeddingPort(embedUri);
+    if (embedResult.ok) {
+      embedPort = embedResult.value;
+    }
+
+    // Create generation port (for expansion) - optional
+    if (!options.noExpand) {
+      const genUri = options.genModel ?? preset.gen;
+      const genResult = await llm.createGenerationPort(genUri);
+      if (genResult.ok) {
+        genPort = genResult.value;
+      }
+    }
+
+    // Create rerank port - optional
+    if (!options.noRerank) {
+      const rerankUri = options.rerankModel ?? preset.rerank;
+      const rerankResult = await llm.createRerankPort(rerankUri);
+      if (rerankResult.ok) {
+        rerankPort = rerankResult.value;
+      }
+    }
+
+    // Create vector index (optional)
+    let vectorIndex: VectorIndexPort | null = null;
+    if (embedPort) {
+      const embedInitResult = await embedPort.init();
+      if (embedInitResult.ok) {
+        const dimensions = embedPort.dimensions();
+        const db = store.getRawDb();
+        const vectorResult = await createVectorIndexPort(db, {
+          model: embedUri,
+          dimensions,
+        });
+        if (vectorResult.ok) {
+          vectorIndex = vectorResult.value;
+        }
+      }
+    }
+
+    const deps: HybridSearchDeps = {
+      store,
+      config,
+      vectorIndex,
+      embedPort,
+      genPort,
+      rerankPort,
+    };
+
+    const result = await searchHybrid(deps, queryText, {
+      ...options,
+      limit,
+    });
+
+    if (!result.ok) {
+      return { success: false, error: result.error.message };
+    }
+
+    return { success: true, data: result.value };
+  } finally {
+    if (embedPort) {
+      await embedPort.dispose();
+    }
+    if (genPort) {
+      await genPort.dispose();
+    }
+    if (rerankPort) {
+      await rerankPort.dispose();
+    }
+    await store.close();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Formatters
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Import shared formatters dynamically to keep module loading fast
+// and avoid circular dependencies
+
+/**
+ * Output explain data to stderr using pipeline formatters.
+ */
+function outputExplainToStderr(data: SearchResults): void {
+  const explain = data.meta.explain;
+  if (!explain) {
+    return;
+  }
+
+  // Import pipeline formatters synchronously (they're lightweight)
+  const {
+    formatExplain,
+    formatResultExplain,
+  } = require('../../pipeline/explain');
+  process.stderr.write(`${formatExplain(explain.lines)}\n`);
+  process.stderr.write(`${formatResultExplain(explain.results)}\n`);
+}
+
+/**
+ * Format query result for output.
+ * Uses shared formatSearchResults for consistent output across search commands.
+ */
+export function formatQuery(
+  result: QueryResult,
+  options: QueryFormatOptions
+): string {
+  if (!result.success) {
+    return options.format === 'json'
+      ? JSON.stringify({
+          error: { code: 'QUERY_FAILED', message: result.error },
+        })
+      : `Error: ${result.error}`;
+  }
+
+  // Output explain to stderr if present (async but best-effort)
+  outputExplainToStderr(result.data);
+
+  // Use shared formatter for consistent output
+  // Dynamic import to keep module loading fast
+  const { formatSearchResults } = require('../format/search-results');
+  return formatSearchResults(result.data, {
+    format: options.format,
+    full: options.full,
+    lineNumbers: options.lineNumbers,
+  });
+}

package/src/cli/commands/ref-parser.ts

@@ -0,0 +1,108 @@
+/**
+ * Reference parser for document refs.
+ * Pure lexical parsing - NO store/config access.
+ *
+ * @module src/cli/commands/ref-parser
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type RefType = 'docid' | 'uri' | 'collPath';
+
+export interface ParsedRef {
+  type: RefType;
+  /** Normalized ref (without :line suffix) */
+  value: string;
+  /** For collPath type */
+  collection?: string;
+  /** For collPath type */
+  relPath?: string;
+  /** Parsed :line suffix (1-indexed) */
+  line?: number;
+}
+
+export type ParseRefResult = ParsedRef | { error: string };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Top-level regex patterns (perf: avoid recreating in functions)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const DOCID_PATTERN = /^#[a-f0-9]{6,8}$/;
+const LINE_SUFFIX_PATTERN = /:(\d+)$/;
+const GLOB_PATTERN = /[*?[\]]/;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Parser Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a single ref string.
+ * - Docid: starts with # (no :line suffix allowed)
+ * - URI: starts with gno:// (optional :N suffix)
+ * - Else: collection/path (optional :N suffix)
+ */
+export function parseRef(ref: string): ParseRefResult {
+  // 1. DocID: starts with #, validate pattern
+  if (ref.startsWith('#')) {
+    if (ref.includes(':')) {
+      return { error: 'Docid refs cannot have :line suffix' };
+    }
+    if (!DOCID_PATTERN.test(ref)) {
+      return { error: `Invalid docid format: ${ref}` };
+    }
+    return { type: 'docid', value: ref };
+  }
+
+  // 2. Parse optional :line suffix for URI and collPath
+  let line: number | undefined;
+  let baseRef = ref;
+  const lineMatch = ref.match(LINE_SUFFIX_PATTERN);
+  if (lineMatch?.[1]) {
+    const parsed = Number.parseInt(lineMatch[1], 10);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+      return { error: `Invalid line suffix (must be >= 1): ${ref}` };
+    }
+    line = parsed;
+    baseRef = ref.slice(0, -lineMatch[0].length);
+  }
+
+  // 3. URI: starts with gno://
+  if (baseRef.startsWith('gno://')) {
+    return { type: 'uri', value: baseRef, line };
+  }
+
+  // 4. Collection/path: must contain /
+  const slashIdx = baseRef.indexOf('/');
+  if (slashIdx === -1) {
+    return { error: `Invalid ref format (missing /): ${ref}` };
+  }
+  const collection = baseRef.slice(0, slashIdx);
+  const relPath = baseRef.slice(slashIdx + 1);
+
+  return { type: 'collPath', value: baseRef, collection, relPath, line };
+}
+
+/**
+ * Split comma-separated refs. Does NOT expand globs.
+ */
+export function splitRefs(refs: string[]): string[] {
+  const result: string[] = [];
+  for (const r of refs) {
+    for (const part of r.split(',')) {
+      const trimmed = part.trim();
+      if (trimmed) {
+        result.push(trimmed);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Check if a ref contains glob characters.
+ */
+export function isGlobPattern(ref: string): boolean {
+  return GLOB_PATTERN.test(ref);
+}

package/src/cli/commands/reset.ts

@@ -0,0 +1,191 @@
+/**
+ * gno reset - Reset GNO to fresh state
+ *
+ * Deletes all config, data, and cache directories.
+ */
+
+// node:fs/promises: rm and stat for recursive directory deletion (no Bun equivalent)
+import { rm, stat } from 'node:fs/promises';
+// node:os: homedir for platform-agnostic home directory (no Bun equivalent)
+import { homedir } from 'node:os';
+// node:path: path manipulation utilities (no Bun equivalent)
+import { isAbsolute, normalize, sep } from 'node:path';
+import { resolveDirs } from '../../app/constants';
+import { CliError } from '../errors';
+
+interface ResetOptions {
+  confirm?: boolean;
+  keepConfig?: boolean;
+  keepCache?: boolean;
+}
+
+interface DirResult {
+  path: string;
+  status: 'deleted' | 'missing' | 'kept';
+  error?: string;
+}
+
+interface ResetResult {
+  results: DirResult[];
+  errors: string[];
+}
+
+// Forbidden paths that should never be deleted
+const FORBIDDEN_PATHS = new Set([
+  '/',
+  '/Users',
+  '/home',
+  '/var',
+  '/etc',
+  '/tmp',
+]);
+
+/**
+ * Validate a path is safe to delete.
+ * Must be absolute, under home directory, and not a system path.
+ */
+function assertSafePath(path: string, label: string): void {
+  const normalized = normalize(path);
+
+  // Must be absolute
+  if (!isAbsolute(normalized)) {
+    throw new CliError('VALIDATION', `${label} path must be absolute: ${path}`);
+  }
+
+  // Must not be a forbidden system path
+  if (
+    FORBIDDEN_PATHS.has(normalized) ||
+    FORBIDDEN_PATHS.has(`${normalized}${sep}`)
+  ) {
+    throw new CliError('VALIDATION', `Refusing to delete system path: ${path}`);
+  }
+
+  // Must be under home directory (for user safety)
+  const home = homedir();
+  if (!normalized.startsWith(home + sep) && normalized !== home) {
+    throw new CliError(
+      'VALIDATION',
+      `${label} path must be under home directory: ${path}`
+    );
+  }
+
+  // Must not be home directory itself
+  if (normalized === home || normalized === home + sep) {
+    throw new CliError(
+      'VALIDATION',
+      `Refusing to delete home directory: ${path}`
+    );
+  }
+}
+
+/**
+ * Reset GNO by deleting directories.
+ */
+export async function reset(options: ResetOptions): Promise<ResetResult> {
+  if (!options.confirm) {
+    throw new CliError(
+      'VALIDATION',
+      'Reset requires --confirm or --yes flag to prevent accidental data loss'
+    );
+  }
+
+  const dirs = resolveDirs();
+  const results: DirResult[] = [];
+  const errors: string[] = [];
+
+  // Validate all paths before deleting anything
+  assertSafePath(dirs.data, 'Data');
+  if (!options.keepConfig) {
+    assertSafePath(dirs.config, 'Config');
+  }
+  if (!options.keepCache) {
+    assertSafePath(dirs.cache, 'Cache');
+  }
+
+  // Delete data directory (always, contains index DB)
+  results.push(await rmDir(dirs.data));
+
+  // Delete config unless --keep-config
+  if (options.keepConfig) {
+    results.push({ path: dirs.config, status: 'kept' });
+  } else {
+    results.push(await rmDir(dirs.config));
+  }
+
+  // Delete cache unless --keep-cache
+  if (options.keepCache) {
+    results.push({ path: dirs.cache, status: 'kept' });
+  } else {
+    results.push(await rmDir(dirs.cache));
+  }
+
+  // Collect errors
+  for (const r of results) {
+    if (r.error) {
+      errors.push(`${r.path}: ${r.error}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new CliError('RUNTIME', `Reset failed:\n${errors.join('\n')}`);
+  }
+
+  return { results, errors };
+}
+
+async function rmDir(path: string): Promise<DirResult> {
+  try {
+    // Check if exists first
+    await stat(path);
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === 'ENOENT') {
+      return { path, status: 'missing' };
+    }
+    return { path, status: 'missing', error: err.message };
+  }
+
+  try {
+    await rm(path, { recursive: true, force: true });
+    return { path, status: 'deleted' };
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    return { path, status: 'missing', error: err.message };
+  }
+}
+
+/**
+ * Format reset result for terminal output.
+ */
+export function formatReset(result: ResetResult): string {
+  const deleted = result.results.filter((r) => r.status === 'deleted');
+  const missing = result.results.filter((r) => r.status === 'missing');
+  const kept = result.results.filter((r) => r.status === 'kept');
+
+  const lines: string[] = ['GNO reset complete.', ''];
+
+  if (deleted.length > 0) {
+    lines.push('Deleted:');
+    for (const r of deleted) {
+      lines.push(`  ${r.path}`);
+    }
+  }
+
+  if (missing.length > 0) {
+    lines.push('');
+    lines.push('Already missing:');
+    for (const r of missing) {
+      lines.push(`  ${r.path}`);
+    }
+  }
+
+  if (kept.length > 0) {
+    lines.push('');
+    lines.push('Kept:');
+    for (const r of kept) {
+      lines.push(`  ${r.path}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/cli/commands/search.ts

@@ -0,0 +1,136 @@
+/**
+ * gno search command implementation.
+ * BM25 keyword search over indexed documents.
+ *
+ * @module src/cli/commands/search
+ */
+
+import { searchBm25 } from '../../pipeline/search';
+import type { SearchOptions, SearchResults } from '../../pipeline/types';
+import {
+  type FormatOptions,
+  formatSearchResults,
+} from '../format/search-results';
+import { initStore } from './shared';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SearchCommandOptions = SearchOptions & {
+  /** Override config path */
+  configPath?: string;
+  /** Output as JSON */
+  json?: boolean;
+  /** Output as Markdown */
+  md?: boolean;
+  /** Output as CSV */
+  csv?: boolean;
+  /** Output as XML */
+  xml?: boolean;
+  /** Output files only */
+  files?: boolean;
+};
+
+export type SearchResult =
+  | { success: true; data: SearchResults }
+  | { success: false; error: string; isValidation?: boolean };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Command Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Execute gno search command.
+ */
+export async function search(
+  query: string,
+  options: SearchCommandOptions = {}
+): Promise<SearchResult> {
+  // Adjust default limit based on output format
+  const isStructured =
+    options.json || options.files || options.csv || options.xml;
+  const limit = options.limit ?? (isStructured ? 20 : 5);
+
+  const initResult = await initStore({
+    configPath: options.configPath,
+    collection: options.collection,
+  });
+
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+
+  const { store } = initResult;
+
+  try {
+    const result = await searchBm25(store, query, {
+      ...options,
+      limit,
+    });
+
+    if (!result.ok) {
+      // Map INVALID_INPUT to validation error for proper exit code
+      const isValidation = result.error.code === 'INVALID_INPUT';
+      return {
+        success: false,
+        error: result.error.message,
+        isValidation,
+      };
+    }
+
+    return { success: true, data: result.value };
+  } finally {
+    await store.close();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Formatter
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get output format from options.
+ */
+function getFormatType(options: SearchCommandOptions): FormatOptions['format'] {
+  if (options.json) {
+    return 'json';
+  }
+  if (options.files) {
+    return 'files';
+  }
+  if (options.csv) {
+    return 'csv';
+  }
+  if (options.md) {
+    return 'md';
+  }
+  if (options.xml) {
+    return 'xml';
+  }
+  return 'terminal';
+}
+
+/**
+ * Format search result for output.
+ */
+export function formatSearch(
+  result: SearchResult,
+  options: SearchCommandOptions
+): string {
+  if (!result.success) {
+    return options.json
+      ? JSON.stringify({
+          error: { code: 'QUERY_FAILED', message: result.error },
+        })
+      : `Error: ${result.error}`;
+  }
+
+  const formatOpts: FormatOptions = {
+    format: getFormatType(options),
+    full: options.full,
+    lineNumbers: options.lineNumbers,
+  };
+
+  return formatSearchResults(result.data, formatOpts);
+}