@gmickel/gno 0.3.0

package/src/cli/context.ts

@@ -0,0 +1,64 @@
+/**
+ * Global CLI context resolution.
+ * Handles global options, NO_COLOR support, etc.
+ *
+ * @module src/cli/context
+ */
+
+import { setColorsEnabled } from './colors';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface GlobalOptions {
+  index: string;
+  config?: string;
+  color: boolean;
+  verbose: boolean;
+  yes: boolean;
+  quiet: boolean;
+  json: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Parsing (pure - no side effects)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse global options from Commander raw opts (pure function).
+ * Supports NO_COLOR env var (https://no-color.org/).
+ */
+export function parseGlobalOptions(
+  raw: Record<string, unknown>,
+  env = process.env
+): GlobalOptions {
+  // NO_COLOR env var support (https://no-color.org/)
+  const noColorEnv = env.NO_COLOR !== undefined && env.NO_COLOR !== '';
+  // --no-color sets color to false in Commander
+  const noColorFlag = raw.color === false;
+
+  const colorEnabled = !(noColorEnv || noColorFlag);
+
+  return {
+    index: (raw.index as string) ?? 'default',
+    config: raw.config as string | undefined,
+    color: colorEnabled,
+    verbose: Boolean(raw.verbose),
+    yes: Boolean(raw.yes),
+    quiet: Boolean(raw.quiet),
+    json: Boolean(raw.json),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Side Effects
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Apply global options side effects (colors, etc).
+ * Should be called exactly once per CLI invocation.
+ */
+export function applyGlobalOptions(globals: GlobalOptions): void {
+  setColorsEnabled(globals.color);
+}

package/src/cli/errors.ts

@@ -0,0 +1,64 @@
+/**
+ * CLI error model aligned to spec.
+ * Exit codes: 0=success, 1=validation, 2=runtime
+ *
+ * @module src/cli/errors
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type CliErrorCode = 'VALIDATION' | 'RUNTIME';
+
+export class CliError extends Error {
+  readonly code: CliErrorCode;
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    code: CliErrorCode,
+    message: string,
+    details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = 'CliError';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Exit Codes
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function exitCodeFor(err: CliError): 1 | 2 {
+  return err.code === 'VALIDATION' ? 1 : 2;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Formatting
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ErrorFormatOptions {
+  json?: boolean;
+}
+
+/**
+ * Format error for output.
+ * JSON mode returns { error: { code, message, details } } envelope.
+ */
+export function formatErrorForOutput(
+  err: CliError,
+  options: ErrorFormatOptions = {}
+): string {
+  if (options.json) {
+    return JSON.stringify({
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.details && { details: err.details }),
+      },
+    });
+  }
+  return `Error: ${err.message}`;
+}

package/src/cli/format/search-results.ts

@@ -0,0 +1,211 @@
+/**
+ * Shared formatters for search/vsearch commands.
+ * Centralizes output formatting to avoid duplication.
+ *
+ * @module src/cli/format/searchResults
+ */
+
+import type { SearchResults } from '../../pipeline/types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FormatOptions {
+  full?: boolean;
+  lineNumbers?: boolean;
+  format: 'terminal' | 'json' | 'files' | 'csv' | 'md' | 'xml';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SNIPPET_LIMIT_TERMINAL = 200;
+const SNIPPET_LIMIT_STRUCTURED = 500;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Main Formatter
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Format search results based on output format and options.
+ */
+export function formatSearchResults(
+  data: SearchResults,
+  options: FormatOptions
+): string {
+  switch (options.format) {
+    case 'json':
+      return JSON.stringify(data, null, 2);
+    case 'files':
+      return formatFiles(data);
+    case 'csv':
+      return formatCsv(data);
+    case 'md':
+      return formatMarkdown(data, options);
+    case 'xml':
+      return formatXml(data, options);
+    default:
+      return formatTerminal(data, options);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Format Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Format as line protocol per spec.
+ * Output: #docid,score,gno://collection/path
+ */
+function formatFiles(data: SearchResults): string {
+  return data.results
+    .map((r) => {
+      // Defensive: ensure docid starts with #
+      const docid = r.docid.startsWith('#') ? r.docid : `#${r.docid}`;
+      return `${docid},${r.score.toFixed(4)},${r.uri}`;
+    })
+    .join('\n');
+}
+
+function formatTerminal(data: SearchResults, options: FormatOptions): string {
+  if (data.results.length === 0) {
+    return 'No results found.';
+  }
+
+  const lines: string[] = [];
+  for (const r of data.results) {
+    lines.push(`[${r.docid}] ${r.uri} (score: ${r.score.toFixed(2)})`);
+    if (r.title) {
+      lines.push(`  ${r.title}`);
+    }
+    if (r.snippet) {
+      const content = options.full
+        ? r.snippet
+        : truncate(r.snippet, SNIPPET_LIMIT_TERMINAL);
+      // For --full, snippetRange is undefined; start at line 1
+      const startLine = r.snippetRange?.startLine ?? 1;
+      const formatted = options.lineNumbers
+        ? addLineNumbers(content, startLine)
+        : content;
+      // Indent multiline snippets
+      lines.push(`  ${formatted.replace(/\n/g, '\n  ')}`);
+    }
+    lines.push('');
+  }
+  lines.push(
+    `${data.meta.totalResults} result(s) for "${data.meta.query}" (${data.meta.mode})`
+  );
+  return lines.join('\n');
+}
+
+function formatMarkdown(data: SearchResults, options: FormatOptions): string {
+  const modeLabel = data.meta.mode === 'vector' ? 'Vector ' : '';
+  if (data.results.length === 0) {
+    return `# ${modeLabel}Search Results\n\nNo results found for "${data.meta.query}".`;
+  }
+
+  const lines: string[] = [];
+  lines.push(`# ${modeLabel}Search Results for "${data.meta.query}"`);
+  lines.push('');
+  lines.push(`*${data.meta.totalResults} result(s)*`);
+  lines.push('');
+
+  for (const r of data.results) {
+    lines.push(`## ${r.title || r.source.relPath}`);
+    lines.push('');
+    lines.push(`- **URI**: \`${r.uri}\``);
+    lines.push(`- **Score**: ${r.score.toFixed(2)}`);
+    lines.push(`- **DocID**: \`${r.docid}\``);
+    if (r.snippet) {
+      const content = options.full
+        ? r.snippet
+        : truncate(r.snippet, SNIPPET_LIMIT_STRUCTURED);
+      const startLine = r.snippetRange?.startLine ?? 1;
+      const formatted = options.lineNumbers
+        ? addLineNumbers(content, startLine)
+        : content;
+      lines.push('');
+      lines.push('```');
+      lines.push(formatted);
+      lines.push('```');
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function formatCsv(data: SearchResults): string {
+  const lines: string[] = [];
+  lines.push('docid,score,uri,title,relPath');
+  for (const r of data.results) {
+    const title = escapeCsv(r.title ?? '');
+    const relPath = escapeCsv(r.source.relPath);
+    lines.push(
+      `"${r.docid}",${r.score.toFixed(4)},"${r.uri}","${title}","${relPath}"`
+    );
+  }
+  return lines.join('\n');
+}
+
+function formatXml(data: SearchResults, options: FormatOptions): string {
+  const lines: string[] = [];
+  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+  lines.push('<searchResults>');
+  lines.push(
+    `  <meta query="${escapeXml(data.meta.query)}" mode="${data.meta.mode}" total="${data.meta.totalResults}"/>`
+  );
+  for (const r of data.results) {
+    lines.push('  <result>');
+    lines.push(`    <docid>${escapeXml(r.docid)}</docid>`);
+    lines.push(`    <score>${r.score}</score>`);
+    lines.push(`    <uri>${escapeXml(r.uri)}</uri>`);
+    if (r.title) {
+      lines.push(`    <title>${escapeXml(r.title)}</title>`);
+    }
+    lines.push(`    <relPath>${escapeXml(r.source.relPath)}</relPath>`);
+    if (r.snippet) {
+      const content = options.full
+        ? r.snippet
+        : truncate(r.snippet, SNIPPET_LIMIT_STRUCTURED);
+      const startLine = r.snippetRange?.startLine ?? 1;
+      const formatted = options.lineNumbers
+        ? addLineNumbers(content, startLine)
+        : content;
+      lines.push(`    <snippet>${escapeXml(formatted)}</snippet>`);
+    }
+    lines.push('  </result>');
+  }
+  lines.push('</searchResults>');
+  return lines.join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Utility Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+function addLineNumbers(text: string, startLine: number): string {
+  return text
+    .split('\n')
+    .map((line, i) => `${startLine + i}: ${line}`)
+    .join('\n');
+}
+
+function truncate(text: string, limit: number): string {
+  return text.length > limit ? `${text.slice(0, limit)}...` : text;
+}
+
+function escapeCsv(str: string): string {
+  return str.replace(/"/g, '""');
+}
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/src/cli/options.ts

@@ -0,0 +1,183 @@
+/**
+ * Output format selection and validation.
+ * Implements conditional defaults per spec.
+ *
+ * @module src/cli/options
+ */
+
+import { CliError } from './errors';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type OutputFormat = 'terminal' | 'json' | 'files' | 'csv' | 'md' | 'xml';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Format Support Matrix (per spec/cli.md)
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Command IDs for consistent referencing
+export const CMD = {
+  search: 'search',
+  vsearch: 'vsearch',
+  query: 'query',
+  ask: 'ask',
+  get: 'get',
+  multiGet: 'multi-get',
+  ls: 'ls',
+  status: 'status',
+  collectionList: 'collection.list',
+  contextList: 'context.list',
+  contextCheck: 'context.check',
+  modelsList: 'models.list',
+} as const;
+
+export type CommandId = (typeof CMD)[keyof typeof CMD];
+
+const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
+  [CMD.search]: ['terminal', 'json', 'files', 'csv', 'md', 'xml'],
+  [CMD.vsearch]: ['terminal', 'json', 'files', 'csv', 'md', 'xml'],
+  [CMD.query]: ['terminal', 'json', 'files', 'csv', 'md', 'xml'],
+  [CMD.ask]: ['terminal', 'json', 'md'],
+  [CMD.get]: ['terminal', 'json', 'md'],
+  [CMD.multiGet]: ['terminal', 'json', 'files', 'md'],
+  [CMD.ls]: ['terminal', 'json', 'files', 'md'],
+  [CMD.status]: ['terminal', 'json'],
+  [CMD.collectionList]: ['terminal', 'json', 'md'],
+  [CMD.contextList]: ['terminal', 'json', 'md'],
+  [CMD.contextCheck]: ['terminal', 'json', 'md'],
+  [CMD.modelsList]: ['terminal', 'json'],
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Format Selection
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FormatFlags {
+  json?: boolean;
+  files?: boolean;
+  csv?: boolean;
+  md?: boolean;
+  xml?: boolean;
+}
+
+/**
+ * Select output format from flags.
+ * Throws if multiple format flags are set.
+ */
+export function selectOutputFormat(flags: FormatFlags): OutputFormat {
+  const selected: OutputFormat[] = [];
+  if (flags.json) {
+    selected.push('json');
+  }
+  if (flags.files) {
+    selected.push('files');
+  }
+  if (flags.csv) {
+    selected.push('csv');
+  }
+  if (flags.md) {
+    selected.push('md');
+  }
+  if (flags.xml) {
+    selected.push('xml');
+  }
+
+  if (selected.length > 1) {
+    throw new CliError(
+      'VALIDATION',
+      `Conflicting output formats: ${selected.join(', ')}. Choose one.`
+    );
+  }
+
+  return selected[0] ?? 'terminal';
+}
+
+/**
+ * Assert format is supported for command.
+ */
+export function assertFormatSupported(
+  cmd: CommandId,
+  format: OutputFormat
+): void {
+  const supported = FORMAT_SUPPORT[cmd];
+  if (!supported.includes(format)) {
+    throw new CliError(
+      'VALIDATION',
+      `Format --${format} is not supported by '${cmd}'. Supported: ${supported.join(', ')}`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Conditional Defaults
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Get default limit based on format.
+ * Spec: 5 for terminal, 20 for structured output.
+ */
+export function getDefaultLimit(format: OutputFormat): number {
+  return format === 'terminal' ? 5 : 20;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Numeric Option Parsing
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse and validate a positive integer option.
+ * Throws CliError on invalid input.
+ */
+export function parsePositiveInt(name: string, value: unknown): number {
+  if (value === undefined || value === null) {
+    throw new CliError('VALIDATION', `--${name} requires a value`);
+  }
+  const strValue = String(value);
+  const num = Number.parseInt(strValue, 10);
+  if (Number.isNaN(num)) {
+    throw new CliError(
+      'VALIDATION',
+      `--${name} must be a number, got: ${strValue}`
+    );
+  }
+  if (num < 1) {
+    throw new CliError('VALIDATION', `--${name} must be positive, got: ${num}`);
+  }
+  return num;
+}
+
+/**
+ * Parse optional positive integer, returning undefined if not provided.
+ */
+export function parseOptionalPositiveInt(
+  name: string,
+  value: unknown
+): number | undefined {
+  if (value === undefined || value === null) {
+    return;
+  }
+  return parsePositiveInt(name, value);
+}
+
+/**
+ * Parse optional float, returning undefined if not provided.
+ */
+export function parseOptionalFloat(
+  name: string,
+  value: unknown
+): number | undefined {
+  if (value === undefined || value === null) {
+    return;
+  }
+  const strValue = String(value);
+  const num = Number.parseFloat(strValue);
+  if (Number.isNaN(num)) {
+    throw new CliError(
+      'VALIDATION',
+      `--${name} must be a number, got: ${strValue}`
+    );
+  }
+  return num;
+}