@gmickel/gno 0.3.0

package/src/cli/run.ts

@@ -0,0 +1,213 @@
+/**
+ * CLI runner - main entry point.
+ * Parses argv, handles errors, returns exit code.
+ *
+ * @module src/cli/run
+ */
+
+import { CommanderError } from 'commander';
+import { CLI_NAME, PRODUCT_NAME } from '../app/constants';
+import { CliError, exitCodeFor, formatErrorForOutput } from './errors';
+import { createProgram, resetGlobals } from './program';
+
+/**
+ * Check if argv contains --json flag (before end-of-options marker).
+ * Used for error formatting before command parsing completes.
+ */
+function argvWantsJson(argv: string[]): boolean {
+  for (const arg of argv) {
+    if (arg === '--') {
+      break; // Stop at end-of-options marker
+    }
+    if (arg === '--json') {
+      return true;
+    }
+  }
+  return false;
+}
+
+// Known global flags (boolean) - includes both --no-color and --color (negatable)
+const KNOWN_BOOL_FLAGS = new Set([
+  '--color',
+  '--no-color',
+  '--verbose',
+  '--yes',
+  '-q',
+  '--quiet',
+  '--json',
+]);
+
+// Known global flags that take values (--flag value or --flag=value)
+const KNOWN_VALUE_FLAGS = ['--index', '--config'] as const;
+
+/**
+ * Check if arg is a known value flag (--index, --config, or --index=val form).
+ */
+function isKnownValueFlag(arg: string): boolean {
+  for (const flag of KNOWN_VALUE_FLAGS) {
+    if (arg === flag || arg.startsWith(`${flag}=`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Check if argv has no subcommand (only known global flags).
+ * Returns true for: gno, gno --json, gno --quiet --verbose
+ * Returns false for: gno search, gno init, gno --help, gno --badoption, etc.
+ *
+ * Edge cases handled:
+ * - `gno -- search` → false (content after --)
+ * - `gno --index` → false (missing value, let Commander error)
+ * - `gno --index=foo` → true (equals form supported)
+ * - `gno --color` → true (negatable flag pair)
+ */
+function hasNoSubcommand(argv: string[]): boolean {
+  // Skip first two (node, script path)
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i] as string; // Guaranteed by loop bounds
+
+    // End of options marker
+    if (arg === '--') {
+      // Only "no subcommand" if nothing comes after --
+      return i === argv.length - 1;
+    }
+
+    // Known boolean flag - skip
+    if (KNOWN_BOOL_FLAGS.has(arg)) {
+      continue;
+    }
+
+    // Known value flag with = syntax (--index=foo)
+    if (isKnownValueFlag(arg) && arg.includes('=')) {
+      continue;
+    }
+
+    // Known value flag without = (--index foo)
+    if (isKnownValueFlag(arg)) {
+      const nextArg = argv[i + 1];
+      // Missing value or next is a flag → let Commander handle/error
+      if (nextArg === undefined || nextArg.startsWith('-')) {
+        return false;
+      }
+      i += 1; // Skip the value
+      continue;
+    }
+
+    // Anything else (subcommand, unknown flag, --help, etc.) → not "no subcommand"
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Print concise help when gno is run with no subcommand.
+ * Per clig.dev: show brief usage, examples, and pointer to --help.
+ */
+function printConciseHelp(opts: { json: boolean }): void {
+  if (opts.json) {
+    const help = {
+      name: CLI_NAME,
+      description: `${PRODUCT_NAME} - Local Knowledge Index and Retrieval`,
+      usage: `${CLI_NAME} <command> [options]`,
+      examples: [
+        `${CLI_NAME} init ~/docs --name docs`,
+        `${CLI_NAME} index`,
+        `${CLI_NAME} ask "your question"`,
+      ],
+      help: `Run ${CLI_NAME} --help for full command list`,
+    };
+    process.stdout.write(`${JSON.stringify(help, null, 2)}\n`);
+  } else {
+    process.stdout.write(`${PRODUCT_NAME} - Local Knowledge Index and Retrieval
+
+Usage: ${CLI_NAME} <command> [options]
+
+Quick start:
+  ${CLI_NAME} init ~/docs --name docs    Initialize with a collection
+  ${CLI_NAME} index                      Build the index
+  ${CLI_NAME} ask "your question"        Search your knowledge
+
+Run '${CLI_NAME} --help' for full command list.
+`);
+  }
+}
+
+/**
+ * Run CLI and return exit code.
+ * No process.exit() - caller sets process.exitCode.
+ */
+export async function runCli(argv: string[]): Promise<number> {
+  // Reset global state for clean invocation (important for testing)
+  resetGlobals();
+
+  const isJson = argvWantsJson(argv);
+
+  // Handle "no subcommand" case before Commander (avoids full help display)
+  if (hasNoSubcommand(argv)) {
+    printConciseHelp({ json: isJson });
+    return 0;
+  }
+
+  const program = createProgram();
+
+  // Suppress Commander's stderr output in JSON mode
+  // so agents get only our structured JSON envelope
+  if (isJson) {
+    program.configureOutput({
+      writeErr: () => {
+        // Intentionally empty: suppress Commander's stderr
+      },
+    });
+  }
+
+  try {
+    await program.parseAsync(argv);
+    return 0;
+  } catch (err) {
+    // Handle CliError with proper JSON formatting
+    if (err instanceof CliError) {
+      const output = formatErrorForOutput(err, { json: isJson });
+      process.stderr.write(`${output}\n`);
+      return exitCodeFor(err);
+    }
+
+    // Handle Commander errors (exitOverride throws these)
+    if (err instanceof CommanderError) {
+      // Help/version are "successful" exits
+      // commander.helpDisplayed: --help or -h flag
+      // commander.help: help subcommand (e.g., help collection)
+      // commander.version: --version or -V flag
+      if (
+        err.code === 'commander.helpDisplayed' ||
+        err.code === 'commander.help' ||
+        err.code === 'commander.version'
+      ) {
+        return 0;
+      }
+
+      // Validation errors (missing args, unknown options)
+      // Always emit JSON envelope in JSON mode (Commander stderr suppressed above)
+      if (isJson) {
+        const cliErr = new CliError('VALIDATION', err.message, {
+          commanderCode: err.code,
+        });
+        const output = formatErrorForOutput(cliErr, { json: true });
+        process.stderr.write(`${output}\n`);
+      }
+      return 1;
+    }
+
+    // Unexpected errors
+    const message = err instanceof Error ? err.message : String(err);
+    if (isJson) {
+      const cliErr = new CliError('RUNTIME', message);
+      const output = formatErrorForOutput(cliErr, { json: true });
+      process.stderr.write(`${output}\n`);
+    } else {
+      process.stderr.write(`Error: ${message}\n`);
+    }
+    return 2;
+  }
+}

package/src/cli/ui.ts

@@ -0,0 +1,92 @@
+/**
+ * CLI output utilities with policy-based routing.
+ * Implements stdout/stderr discipline per clig.dev guidelines:
+ * - stdout: data output (for piping/scripting)
+ * - stderr: messaging, progress, hints (for humans)
+ *
+ * @module src/cli/ui
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface OutputPolicy {
+  quiet: boolean;
+  json: boolean;
+  isTTY: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Policy Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if hints/progress should be shown based on output policy.
+ * Hints are suppressed when: quiet mode, JSON mode, or non-TTY.
+ */
+export function shouldShowHints(policy: OutputPolicy): boolean {
+  return !(policy.quiet || policy.json) && policy.isTTY;
+}
+
+/**
+ * Create output policy from global options.
+ */
+export function createOutputPolicy(opts: {
+  quiet: boolean;
+  json: boolean;
+}): OutputPolicy {
+  return {
+    quiet: opts.quiet,
+    json: opts.json,
+    isTTY: process.stderr.isTTY ?? false,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Output Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Write data to stdout (for piping/scripting).
+ * Not affected by quiet mode - data is always emitted.
+ */
+export function data(msg: string): void {
+  process.stdout.write(`${msg}\n`);
+}
+
+/**
+ * Write info message to stderr.
+ * Not affected by quiet mode - important messages are always shown.
+ */
+export function info(msg: string): void {
+  process.stderr.write(`${msg}\n`);
+}
+
+/**
+ * Write error message to stderr.
+ * Not affected by quiet mode - errors are always shown.
+ */
+export function error(msg: string): void {
+  process.stderr.write(`${msg}\n`);
+}
+
+/**
+ * Write hint/progress message to stderr (gated by policy).
+ * Suppressed in quiet mode, JSON mode, or non-TTY.
+ */
+export function hint(msg: string, policy: OutputPolicy): void {
+  if (shouldShowHints(policy)) {
+    process.stderr.write(`${msg}\n`);
+  }
+}
+
+/**
+ * Write warning message to stderr (gated by quiet only).
+ * Shown unless explicitly silenced with --quiet.
+ */
+export function warn(msg: string, policy: OutputPolicy): void {
+  if (!policy.quiet) {
+    process.stderr.write(`${msg}\n`);
+  }
+}

package/src/config/defaults.ts

@@ -0,0 +1,20 @@
+/**
+ * Default config factory for GNO.
+ *
+ * @module src/config/defaults
+ */
+
+import { CONFIG_VERSION, type Config, DEFAULT_FTS_TOKENIZER } from './types';
+
+/**
+ * Create a default config object.
+ * Used when initializing a new GNO installation.
+ */
+export function createDefaultConfig(): Config {
+  return {
+    version: CONFIG_VERSION,
+    ftsTokenizer: DEFAULT_FTS_TOKENIZER,
+    collections: [],
+    contexts: [],
+  };
+}

package/src/config/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Config module public API.
+ *
+ * @module src/config
+ */
+
+export { createDefaultConfig } from './defaults';
+// Loading
+export {
+  isInitialized,
+  type LoadError,
+  type LoadResult,
+  loadConfig,
+  loadConfigFromPath,
+  loadConfigOrNull,
+} from './loader';
+
+// Path utilities
+export {
+  configExists,
+  expandPath,
+  getConfigPath,
+  getConfigPaths,
+  pathExists,
+  type ResolvedDirs,
+  toAbsolutePath,
+} from './paths';
+// Saving
+export {
+  ensureDirectories,
+  type SaveError,
+  type SaveResult,
+  saveConfig,
+  saveConfigToPath,
+} from './saver';
+// Types and schemas
+export {
+  CONFIG_VERSION,
+  type Collection,
+  CollectionSchema,
+  type Config,
+  ConfigSchema,
+  type Context,
+  ContextSchema,
+  DEFAULT_EXCLUDES,
+  DEFAULT_FTS_TOKENIZER,
+  DEFAULT_PATTERN,
+  FTS_TOKENIZERS,
+  type FtsTokenizer,
+  getCollectionFromScope,
+  isValidLanguageHint,
+  parseScope,
+  type ScopeType,
+  ScopeTypeSchema,
+} from './types';

package/src/config/loader.ts

@@ -0,0 +1,161 @@
+/**
+ * Config loading and validation.
+ * Loads YAML config and validates against Zod schema.
+ *
+ * @module src/config/loader
+ */
+
+import type { ZodError } from 'zod';
+import { configExists, expandPath, getConfigPaths } from './paths';
+import { CONFIG_VERSION, type Config, ConfigSchema } from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Result Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type LoadResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: LoadError };
+
+export type LoadError =
+  | { code: 'NOT_FOUND'; message: string; path: string }
+  | { code: 'PARSE_ERROR'; message: string; details: string }
+  | { code: 'VALIDATION_ERROR'; message: string; issues: ZodError['issues'] }
+  | {
+      code: 'VERSION_MISMATCH';
+      message: string;
+      found: string;
+      expected: string;
+    }
+  | { code: 'IO_ERROR'; message: string; cause: Error };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Loading Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Load config from default location or specified path.
+ * Priority: configPath arg > GNO_CONFIG_DIR env > platform default
+ */
+export function loadConfig(configPath?: string): Promise<LoadResult<Config>> {
+  const paths = getConfigPaths();
+  const targetPath = configPath ? expandPath(configPath) : paths.configFile;
+
+  return loadConfigFromPath(targetPath);
+}
+
+/**
+ * Load config from a specific file path.
+ */
+export async function loadConfigFromPath(
+  filePath: string
+): Promise<LoadResult<Config>> {
+  // Check file exists
+  const file = Bun.file(filePath);
+  const exists = await file.exists();
+
+  if (!exists) {
+    return {
+      ok: false,
+      error: {
+        code: 'NOT_FOUND',
+        message: `Config file not found: ${filePath}`,
+        path: filePath,
+      },
+    };
+  }
+
+  // Read file contents
+  let content: string;
+  try {
+    content = await file.text();
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: 'IO_ERROR',
+        message: `Failed to read config file: ${filePath}`,
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+      },
+    };
+  }
+
+  // Parse YAML
+  let parsed: unknown;
+  try {
+    parsed = Bun.YAML.parse(content);
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: 'PARSE_ERROR',
+        message: 'Invalid YAML syntax',
+        details: cause instanceof Error ? cause.message : String(cause),
+      },
+    };
+  }
+
+  // Check version before full validation
+  if (
+    typeof parsed === 'object' &&
+    parsed !== null &&
+    'version' in parsed &&
+    parsed.version !== CONFIG_VERSION
+  ) {
+    return {
+      ok: false,
+      error: {
+        code: 'VERSION_MISMATCH',
+        message: `Config version mismatch. Found "${String(parsed.version)}", expected "${CONFIG_VERSION}"`,
+        found: String(parsed.version),
+        expected: CONFIG_VERSION,
+      },
+    };
+  }
+
+  // Validate against schema
+  const result = ConfigSchema.safeParse(parsed);
+
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: 'VALIDATION_ERROR',
+        message: 'Config validation failed',
+        issues: result.error.issues,
+      },
+    };
+  }
+
+  return { ok: true, value: result.data };
+}
+
+/**
+ * Load config, returning null if not found (convenience wrapper).
+ * Throws on parse/validation errors.
+ */
+export async function loadConfigOrNull(
+  configPath?: string
+): Promise<Config | null> {
+  const result = await loadConfig(configPath);
+
+  if (!result.ok) {
+    if (result.error.code === 'NOT_FOUND') {
+      return null;
+    }
+    throw new Error(result.error.message);
+  }
+
+  return result.value;
+}
+
+/**
+ * Check if GNO is initialized (config exists).
+ */
+export function isInitialized(configPath?: string): Promise<boolean> {
+  if (configPath) {
+    const file = Bun.file(expandPath(configPath));
+    return file.exists();
+  }
+  return configExists();
+}

package/src/config/paths.ts

@@ -0,0 +1,87 @@
+/**
+ * Config path resolution utilities.
+ * Wraps constants.ts for config-specific path operations.
+ *
+ * @module src/config/paths
+ */
+
+import { homedir } from 'node:os';
+import { isAbsolute, join, normalize } from 'node:path';
+import {
+  getConfigPath as getConfigPathBase,
+  type ResolvedDirs,
+  resolveDirs,
+} from '../app/constants';
+
+export type { ResolvedDirs } from '../app/constants';
+export { getConfigPath } from '../app/constants';
+
+/**
+ * Resolve ~ to home directory and normalize path.
+ * Converts relative paths with ~ prefix to absolute paths.
+ */
+export function expandPath(inputPath: string): string {
+  if (inputPath.startsWith('~/')) {
+    return join(homedir(), inputPath.slice(2));
+  }
+  if (inputPath === '~') {
+    return homedir();
+  }
+  return normalize(inputPath);
+}
+
+/**
+ * Ensure path is absolute, expanding ~ if needed.
+ * Falls back to current working directory for relative paths.
+ */
+export function toAbsolutePath(inputPath: string, cwd?: string): string {
+  const expanded = expandPath(inputPath);
+  if (isAbsolute(expanded)) {
+    return expanded;
+  }
+  return join(cwd ?? process.cwd(), expanded);
+}
+
+/**
+ * Get all config-related paths.
+ * Returns paths for config file, data dir, and cache dir.
+ */
+export function getConfigPaths(dirs?: ResolvedDirs): {
+  configFile: string;
+  dataDir: string;
+  cacheDir: string;
+  configDir: string;
+} {
+  const resolved = dirs ?? resolveDirs();
+  return {
+    configFile: getConfigPathBase(resolved),
+    configDir: resolved.config,
+    dataDir: resolved.data,
+    cacheDir: resolved.cache,
+  };
+}
+
+/**
+ * Check if config file exists.
+ */
+export function configExists(dirs?: ResolvedDirs): Promise<boolean> {
+  const { configFile } = getConfigPaths(dirs);
+  const file = Bun.file(configFile);
+  return file.exists();
+}
+
+/**
+ * Check if a path exists (file or directory).
+ * Uses fs.stat for cross-platform support (Windows compatible).
+ */
+export async function pathExists(path: string): Promise<boolean> {
+  // Bun.file().exists() only works for files, not directories
+  // Use fs.stat for reliable cross-platform check
+  const { stat } = await import('node:fs/promises');
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}