@gmickel/gno 0.3.0

package/src/config/saver.ts

@@ -0,0 +1,153 @@
+/**
+ * Config saving with atomic writes.
+ * Writes config to temp file, then renames to target (atomic on POSIX).
+ *
+ * @module src/config/saver
+ */
+
+import { mkdir, rename, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { expandPath, getConfigPaths } from './paths';
+import { type Config, ConfigSchema } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Result Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type SaveResult =
+  | { ok: true; path: string }
+  | { ok: false; error: SaveError };
+
+export type SaveError =
+  | { code: 'VALIDATION_ERROR'; message: string }
+  | { code: 'IO_ERROR'; message: string; cause: Error };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Saving Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Save config to default location or specified path.
+ * Uses atomic write: temp file + rename.
+ */
+export function saveConfig(
+  config: Config,
+  configPath?: string
+): Promise<SaveResult> {
+  const paths = getConfigPaths();
+  const targetPath = configPath ? expandPath(configPath) : paths.configFile;
+
+  return saveConfigToPath(config, targetPath);
+}
+
+/**
+ * Save config to a specific file path.
+ * Creates parent directories if needed.
+ * Uses atomic write pattern for safety.
+ */
+export async function saveConfigToPath(
+  config: Config,
+  filePath: string
+): Promise<SaveResult> {
+  // Validate config before saving
+  const validation = ConfigSchema.safeParse(config);
+  if (!validation.success) {
+    return {
+      ok: false,
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: `Invalid config: ${validation.error.issues[0]?.message ?? 'unknown error'}`,
+      },
+    };
+  }
+
+  // Convert to YAML
+  const yamlContent = Bun.YAML.stringify(config);
+
+  // Ensure parent directory exists
+  const dir = dirname(filePath);
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: 'IO_ERROR',
+        message: `Failed to create config directory: ${dir}`,
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+      },
+    };
+  }
+
+  // Write to temp file first (atomic write pattern)
+  // Use timestamp + random suffix to avoid collision
+  const tempPath = join(
+    dir,
+    `.index.yml.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`
+  );
+
+  try {
+    await Bun.write(tempPath, yamlContent);
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: 'IO_ERROR',
+        message: `Failed to write temp config file: ${tempPath}`,
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+      },
+    };
+  }
+
+  // Rename temp to target (atomic on POSIX, needs unlink on Windows)
+  try {
+    // Windows: rename fails if dest exists, so unlink first (ignore if not exists)
+    await unlink(filePath).catch(() => {
+      /* ENOENT ok */
+    });
+    await rename(tempPath, filePath);
+  } catch (cause) {
+    // Clean up temp file on rename failure
+    try {
+      await unlink(tempPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+
+    return {
+      ok: false,
+      error: {
+        code: 'IO_ERROR',
+        message: `Failed to save config file: ${filePath}`,
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+      },
+    };
+  }
+
+  return { ok: true, path: filePath };
+}
+
+/**
+ * Create directories for config, data, and cache.
+ * Called during init to set up GNO storage locations.
+ */
+export async function ensureDirectories(): Promise<SaveResult> {
+  const paths = getConfigPaths();
+
+  try {
+    await mkdir(paths.configDir, { recursive: true });
+    await mkdir(paths.dataDir, { recursive: true });
+    await mkdir(paths.cacheDir, { recursive: true });
+
+    return { ok: true, path: paths.configDir };
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: 'IO_ERROR',
+        message: 'Failed to create GNO directories',
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+      },
+    };
+  }
+}

package/src/config/types.ts

@@ -0,0 +1,280 @@
+/**
+ * Config schema definitions using Zod.
+ * Defines Collection, Context, and Config types for GNO.
+ *
+ * @module src/config/types
+ */
+
+import { z } from 'zod';
+import { URI_PREFIX } from '../app/constants';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Current config version */
+export const CONFIG_VERSION = '1.0';
+
+/** Default glob pattern for file matching */
+export const DEFAULT_PATTERN = '**/*';
+
+/** Default exclude patterns for collections */
+export const DEFAULT_EXCLUDES: readonly string[] = [
+  '.git',
+  'node_modules',
+  '.venv',
+  '.idea',
+  'dist',
+  'build',
+  '__pycache__',
+  '.DS_Store',
+  'Thumbs.db',
+];
+
+/** Valid FTS tokenizer options */
+export const FTS_TOKENIZERS = ['unicode61', 'porter', 'trigram'] as const;
+export type FtsTokenizer = (typeof FTS_TOKENIZERS)[number];
+
+/** Default FTS tokenizer */
+export const DEFAULT_FTS_TOKENIZER: FtsTokenizer = 'unicode61';
+
+/**
+ * BCP-47 language tag pattern (simplified, case-insensitive).
+ * Matches: en, de, fr, zh-CN, zh-Hans, und, en-US, etc.
+ */
+const BCP47_PATTERN = /^[a-z]{2,3}(-[a-z]{2}|-[a-z]{4})?$/i;
+
+/** Validate BCP-47 language hint */
+export function isValidLanguageHint(hint: string): boolean {
+  return BCP47_PATTERN.test(hint);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Collection Schema
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Collection name pattern: lowercase alphanumeric, hyphens, underscores.
+ * 1-64 chars, must start with alphanumeric.
+ */
+const COLLECTION_NAME_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/** Collection scope key pattern: name (1-64 chars) followed by colon */
+const COLLECTION_SCOPE_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}:$/;
+
+export const CollectionSchema = z.object({
+  /** Unique collection identifier (lowercase) */
+  name: z
+    .string()
+    .regex(
+      COLLECTION_NAME_REGEX,
+      'Collection name must be lowercase alphanumeric with hyphens/underscores, 1-64 chars'
+    ),
+
+  /** Absolute path to collection root */
+  path: z.string().min(1, 'Path is required'),
+
+  /** Glob pattern for file matching */
+  pattern: z.string().default(DEFAULT_PATTERN),
+
+  /** Extension allowlist (empty = all) */
+  include: z.array(z.string()).default([]),
+
+  /** Path patterns to skip */
+  exclude: z.array(z.string()).default([...DEFAULT_EXCLUDES]),
+
+  /** Optional shell command to run before indexing */
+  updateCmd: z.string().optional(),
+
+  /** Optional BCP-47 language hint */
+  languageHint: z
+    .string()
+    .refine((val) => isValidLanguageHint(val), {
+      message: 'Invalid BCP-47 language code (e.g., en, de, zh-CN, und)',
+    })
+    .optional(),
+});
+
+export type Collection = z.infer<typeof CollectionSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Context Schema
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Context scope types:
+ * - global: "/" - applies to all documents
+ * - collection: "name:" - applies to a specific collection
+ * - prefix: "gno://collection/path" - applies to documents under a path
+ */
+export const ScopeTypeSchema = z.enum(['global', 'collection', 'prefix']);
+export type ScopeType = z.infer<typeof ScopeTypeSchema>;
+
+/**
+ * Validate scope key format based on type.
+ * - global: must be "/"
+ * - collection: must be "name:" format
+ * - prefix: must be "gno://collection/path" format
+ */
+export const ContextSchema = z
+  .object({
+    /** Type of scope */
+    scopeType: ScopeTypeSchema,
+
+    /** Scope key (format depends on scopeType) */
+    scopeKey: z.string().min(1, 'Scope key is required'),
+
+    /** Context description text */
+    text: z.string().min(1, 'Context text is required'),
+  })
+  .refine(
+    (ctx) => {
+      switch (ctx.scopeType) {
+        case 'global':
+          return ctx.scopeKey === '/';
+        case 'collection':
+          return COLLECTION_SCOPE_REGEX.test(ctx.scopeKey);
+        case 'prefix':
+          return ctx.scopeKey.startsWith(URI_PREFIX);
+        default:
+          return false;
+      }
+    },
+    {
+      message: 'Scope key format does not match scope type',
+    }
+  );
+
+export type Context = z.infer<typeof ContextSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Model Preset Schema
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const ModelPresetSchema = z.object({
+  /** Unique preset identifier */
+  id: z.string().min(1),
+  /** Human-readable name */
+  name: z.string().min(1),
+  /** Embedding model URI (hf: or file:) */
+  embed: z.string().min(1),
+  /** Reranker model URI */
+  rerank: z.string().min(1),
+  /** Generation model URI */
+  gen: z.string().min(1),
+});
+
+export type ModelPreset = z.infer<typeof ModelPresetSchema>;
+
+/** Default model presets */
+export const DEFAULT_MODEL_PRESETS: ModelPreset[] = [
+  {
+    id: 'slim',
+    name: 'Slim (Fast, ~1GB)',
+    embed: 'hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf',
+    rerank:
+      'hf:gpustack/bge-reranker-v2-m3-GGUF/bge-reranker-v2-m3-Q4_K_M.gguf',
+    gen: 'hf:unsloth/Qwen3-1.7B-GGUF/Qwen3-1.7B-Q4_K_M.gguf',
+  },
+  {
+    id: 'balanced',
+    name: 'Balanced (Default, ~2GB)',
+    embed: 'hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf',
+    rerank:
+      'hf:gpustack/bge-reranker-v2-m3-GGUF/bge-reranker-v2-m3-Q4_K_M.gguf',
+    gen: 'hf:ggml-org/SmolLM3-3B-GGUF/SmolLM3-Q4_K_M.gguf',
+  },
+  {
+    id: 'quality',
+    name: 'Quality (Best Answers, ~2.5GB)',
+    embed: 'hf:gpustack/bge-m3-GGUF/bge-m3-Q4_K_M.gguf',
+    rerank:
+      'hf:gpustack/bge-reranker-v2-m3-GGUF/bge-reranker-v2-m3-Q4_K_M.gguf',
+    gen: 'hf:unsloth/Qwen3-4B-Instruct-2507-GGUF/Qwen3-4B-Instruct-2507-Q4_K_M.gguf',
+  },
+];
+
+export const ModelConfigSchema = z.object({
+  /** Active preset ID */
+  activePreset: z.string().default('balanced'),
+  /** Model presets */
+  presets: z.array(ModelPresetSchema).default(DEFAULT_MODEL_PRESETS),
+  /** Model load timeout in ms */
+  loadTimeout: z.number().default(60_000),
+  /** Inference timeout in ms */
+  inferenceTimeout: z.number().default(30_000),
+  /** Keep warm model TTL in ms (5 min) */
+  warmModelTtl: z.number().default(300_000),
+});
+
+export type ModelConfig = z.infer<typeof ModelConfigSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config Schema (root)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const ConfigSchema = z.object({
+  /** Config schema version */
+  version: z.literal(CONFIG_VERSION),
+
+  /** FTS tokenizer (immutable after init) */
+  ftsTokenizer: z.enum(FTS_TOKENIZERS).default(DEFAULT_FTS_TOKENIZER),
+
+  /** Collection definitions */
+  collections: z.array(CollectionSchema).default([]),
+
+  /** Context metadata */
+  contexts: z.array(ContextSchema).default([]),
+
+  /** Model configuration */
+  models: ModelConfigSchema.optional(),
+});
+
+export type Config = z.infer<typeof ConfigSchema>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Scope Utilities
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a scope string into type and key.
+ * Input formats (from CLI):
+ * - "/" -> { type: 'global', key: '/' }
+ * - "notes:" -> { type: 'collection', key: 'notes:' }
+ * - "gno://notes/projects" -> { type: 'prefix', key: 'gno://notes/projects' }
+ */
+export function parseScope(
+  scope: string
+): { type: ScopeType; key: string } | null {
+  if (scope === '/') {
+    return { type: 'global', key: '/' };
+  }
+  if (scope.startsWith(URI_PREFIX)) {
+    return { type: 'prefix', key: scope };
+  }
+  if (COLLECTION_SCOPE_REGEX.test(scope)) {
+    return { type: 'collection', key: scope };
+  }
+  return null;
+}
+
+/**
+ * Extract collection name from a scope key.
+ * - "notes:" -> "notes"
+ * - "gno://notes/path" -> "notes"
+ * - "/" -> null
+ */
+export function getCollectionFromScope(scopeKey: string): string | null {
+  if (scopeKey === '/') {
+    return null;
+  }
+  if (scopeKey.endsWith(':')) {
+    return scopeKey.slice(0, -1);
+  }
+  if (scopeKey.startsWith(URI_PREFIX)) {
+    const rest = scopeKey.slice(URI_PREFIX.length);
+    const slashIndex = rest.indexOf('/');
+    return slashIndex === -1 ? rest : rest.slice(0, slashIndex);
+  }
+  return null;
+}

package/src/converters/adapters/markitdownTs/adapter.ts

@@ -0,0 +1,140 @@
+/**
+ * markitdown-ts adapter for PDF, DOCX, XLSX conversion.
+ * Uses convertBuffer() with bytes for determinism.
+ */
+
+import { MarkItDown } from 'markitdown-ts';
+import {
+  adapterError,
+  corruptError,
+  timeoutError,
+  tooLargeError,
+} from '../../errors';
+import type {
+  Converter,
+  ConvertInput,
+  ConvertResult,
+  ConvertWarning,
+} from '../../types';
+import { ADAPTER_VERSIONS } from '../../versions';
+
+const CONVERTER_ID = 'adapter/markitdown-ts' as const;
+const CONVERTER_VERSION = ADAPTER_VERSIONS['markitdown-ts'];
+
+/** Supported extensions for this adapter */
+const SUPPORTED_EXTENSIONS = ['.pdf', '.docx', '.xlsx'];
+
+/** Supported MIME types */
+const SUPPORTED_MIMES = [
+  'application/pdf',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+];
+
+/**
+ * Create zero-copy Buffer view of Uint8Array.
+ * Assumes input.bytes is immutable (contract requirement).
+ */
+function toBuffer(bytes: Uint8Array): Buffer {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+export const markitdownAdapter: Converter = {
+  id: CONVERTER_ID,
+  version: CONVERTER_VERSION,
+
+  canHandle(mime: string, ext: string): boolean {
+    return SUPPORTED_EXTENSIONS.includes(ext) || SUPPORTED_MIMES.includes(mime);
+  },
+
+  async convert(input: ConvertInput): Promise<ConvertResult> {
+    // 1. Check size limit (defense in depth; EPIC 5 does stat-based pre-check)
+    if (input.bytes.length > input.limits.maxBytes) {
+      return { ok: false, error: tooLargeError(input, CONVERTER_ID) };
+    }
+
+    // 2. Setup timeout handling
+    // Note: markitdown-ts doesn't support AbortSignal, so underlying
+    // work may continue after timeout (known limitation; process isolation future work)
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => {
+        timedOut = true;
+        reject(new Error('TIMEOUT'));
+      }, input.limits.timeoutMs);
+    });
+
+    const converter = new MarkItDown();
+
+    // IMPORTANT: Use convertBuffer with bytes for determinism
+    // Path-based convert() could re-read a modified file
+    // Zero-copy Buffer view (input.bytes is immutable by contract)
+    const workPromise = converter.convertBuffer(toBuffer(input.bytes), {
+      file_extension: input.ext,
+    });
+
+    try {
+      const result = await Promise.race([workPromise, timeoutPromise]);
+
+      // Clear timeout on success
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      if (!result?.markdown) {
+        return {
+          ok: false,
+          error: corruptError(input, CONVERTER_ID, 'Empty conversion result'),
+        };
+      }
+
+      // Emit warnings for suspicious output
+      const warnings: ConvertWarning[] = [];
+      if (result.markdown.length < 10 && input.bytes.length > 1000) {
+        warnings.push({ code: 'LOSSY', message: 'Suspiciously short output' });
+      }
+
+      // NOTE: Canonicalization happens in pipeline.ts, not here
+      return {
+        ok: true,
+        value: {
+          markdown: result.markdown,
+          title: result.title ?? undefined,
+          meta: {
+            converterId: CONVERTER_ID,
+            converterVersion: CONVERTER_VERSION,
+            sourceMime: input.mime,
+            warnings: warnings.length > 0 ? warnings : undefined,
+          },
+        },
+      };
+    } catch (err) {
+      // Clear timeout on error
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      // If we timed out, suppress any later rejection from the work promise
+      // to prevent unhandled rejection crashes
+      if (timedOut) {
+        workPromise.catch(() => {
+          // Intentionally swallowed - work continued after timeout
+        });
+        return { ok: false, error: timeoutError(input, CONVERTER_ID) };
+      }
+
+      // Map adapter errors
+      return {
+        ok: false,
+        error: adapterError(
+          input,
+          CONVERTER_ID,
+          err instanceof Error ? err.message : 'Unknown error',
+          err
+        ),
+      };
+    }
+  },
+};

package/src/converters/adapters/officeparser/adapter.ts

@@ -0,0 +1,126 @@
+/**
+ * officeparser adapter for PPTX conversion.
+ * Uses parseOfficeAsync() with Buffer for in-memory extraction.
+ */
+
+import { parseOfficeAsync } from 'officeparser';
+import { adapterError, corruptError, tooLargeError } from '../../errors';
+import { basenameWithoutExt } from '../../path';
+import type {
+  Converter,
+  ConvertInput,
+  ConvertResult,
+  ConvertWarning,
+} from '../../types';
+import { ADAPTER_VERSIONS } from '../../versions';
+
+const CONVERTER_ID = 'adapter/officeparser' as const;
+const CONVERTER_VERSION = ADAPTER_VERSIONS.officeparser;
+
+/** Supported MIME type */
+const PPTX_MIME =
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation';
+
+/**
+ * Control character pattern built dynamically to avoid lint issues.
+ * Matches U+0000-U+001F and U+007F (all ASCII control chars).
+ */
+const CONTROL_CHAR_PATTERN = new RegExp(
+  `[${String.fromCharCode(0)}-${String.fromCharCode(31)}${String.fromCharCode(127)}]`,
+  'g'
+);
+
+/**
+ * Sanitize title for safe Markdown output.
+ * Removes control chars, collapses whitespace, ensures single line.
+ */
+function sanitizeTitle(title: string): string {
+  return title
+    .replace(/[\r\n]/g, ' ')
+    .replace(CONTROL_CHAR_PATTERN, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Get sanitized title from relative path.
+ */
+function getTitleFromPath(relativePath: string): string {
+  return sanitizeTitle(basenameWithoutExt(relativePath));
+}
+
+/**
+ * Create zero-copy Buffer view of Uint8Array.
+ * Assumes input.bytes is immutable (contract requirement).
+ */
+function toBuffer(bytes: Uint8Array): Buffer {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+
+export const officeparserAdapter: Converter = {
+  id: CONVERTER_ID,
+  version: CONVERTER_VERSION,
+
+  canHandle(mime: string, ext: string): boolean {
+    return ext === '.pptx' || mime === PPTX_MIME;
+  },
+
+  async convert(input: ConvertInput): Promise<ConvertResult> {
+    // Size check (defense in depth; EPIC 5 does stat-based pre-check)
+    if (input.bytes.length > input.limits.maxBytes) {
+      return { ok: false, error: tooLargeError(input, CONVERTER_ID) };
+    }
+
+    try {
+      // Zero-copy Buffer view (input.bytes is immutable by contract)
+      const buffer = toBuffer(input.bytes);
+      const text = await parseOfficeAsync(buffer, {
+        newlineDelimiter: '\n',
+        ignoreNotes: false, // Include speaker notes
+      });
+
+      if (!text || text.trim().length === 0) {
+        return {
+          ok: false,
+          error: corruptError(input, CONVERTER_ID, 'Empty extraction result'),
+        };
+      }
+
+      // Get sanitized title
+      const title = getTitleFromPath(input.relativePath);
+
+      // Convert plain text to Markdown structure
+      const markdown = `# ${title}\n\n${text}`;
+
+      // NOTE: Do NOT canonicalize here - pipeline.ts handles all normalization
+      const warnings: ConvertWarning[] = [];
+      if (markdown.length < 10 && input.bytes.length > 1000) {
+        warnings.push({ code: 'LOSSY', message: 'Suspiciously short output' });
+      }
+
+      return {
+        ok: true,
+        value: {
+          markdown,
+          title,
+          meta: {
+            converterId: CONVERTER_ID,
+            converterVersion: CONVERTER_VERSION,
+            sourceMime: input.mime,
+            warnings: warnings.length > 0 ? warnings : undefined,
+          },
+        },
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: adapterError(
+          input,
+          CONVERTER_ID,
+          err instanceof Error ? err.message : 'Unknown error',
+          err
+        ),
+      };
+    }
+  },
+};