mdcontext 0.0.1 → 0.1.0

package/src/cli/flag-schemas.ts

@@ -0,0 +1,275 @@
+/**
+ * Per-Command Flag Schemas
+ *
+ * Defines the valid flags for each CLI command to enable:
+ * - Unknown flag detection
+ * - Typo suggestions
+ * - Accurate flag/value parsing in the preprocessor
+ */
+
+/**
+ * Type of flag
+ */
+export type FlagType = 'boolean' | 'string'
+
+/**
+ * Flag specification
+ */
+export interface FlagSpec {
+  /** Flag name without leading dashes (e.g., 'json') */
+  name: string
+  /** Flag type: boolean (no value) or string (takes value) */
+  type: FlagType
+  /** Short alias without leading dash (e.g., 'n' for --limit) */
+  alias?: string
+  /** Description for error messages */
+  description?: string
+}
+
+/**
+ * Command flag schema
+ */
+export interface CommandSchema {
+  /** Command name */
+  name: string
+  /** Valid flags for this command */
+  flags: FlagSpec[]
+}
+
+// ============================================================================
+// Shared Flags (used by multiple commands)
+// ============================================================================
+
+const jsonFlag: FlagSpec = {
+  name: 'json',
+  type: 'boolean',
+  description: 'Output as JSON',
+}
+
+const prettyFlag: FlagSpec = {
+  name: 'pretty',
+  type: 'boolean',
+  description: 'Pretty-print JSON output',
+}
+
+const forceFlag: FlagSpec = {
+  name: 'force',
+  type: 'boolean',
+  description: 'Force full rebuild',
+}
+
+const rootFlag: FlagSpec = {
+  name: 'root',
+  type: 'string',
+  alias: 'r',
+  description: 'Root directory',
+}
+
+// ============================================================================
+// Per-Command Schemas
+// ============================================================================
+
+export const indexSchema: CommandSchema = {
+  name: 'index',
+  flags: [
+    {
+      name: 'embed',
+      type: 'boolean',
+      alias: 'e',
+      description: 'Build semantic embeddings',
+    },
+    {
+      name: 'no-embed',
+      type: 'boolean',
+      description: 'Skip semantic search prompt',
+    },
+    {
+      name: 'watch',
+      type: 'boolean',
+      alias: 'w',
+      description: 'Watch for changes',
+    },
+    forceFlag,
+    jsonFlag,
+    prettyFlag,
+  ],
+}
+
+export const searchSchema: CommandSchema = {
+  name: 'search',
+  flags: [
+    {
+      name: 'keyword',
+      type: 'boolean',
+      alias: 'k',
+      description: 'Force keyword search',
+    },
+    {
+      name: 'heading-only',
+      type: 'boolean',
+      alias: 'H',
+      description: 'Search headings only',
+    },
+    {
+      name: 'mode',
+      type: 'string',
+      alias: 'm',
+      description: 'Force search mode (semantic or keyword)',
+    },
+    {
+      name: 'limit',
+      type: 'string',
+      alias: 'n',
+      description: 'Maximum results',
+    },
+    { name: 'threshold', type: 'string', description: 'Similarity threshold' },
+    {
+      name: 'context',
+      type: 'string',
+      alias: 'C',
+      description: 'Lines of context around matches (like grep -C)',
+    },
+    {
+      name: 'before-context',
+      type: 'string',
+      alias: 'B',
+      description: 'Lines of context before matches (like grep -B)',
+    },
+    {
+      name: 'after-context',
+      type: 'string',
+      alias: 'A',
+      description: 'Lines of context after matches (like grep -A)',
+    },
+    jsonFlag,
+    prettyFlag,
+  ],
+}
+
+export const contextSchema: CommandSchema = {
+  name: 'context',
+  flags: [
+    { name: 'tokens', type: 'string', alias: 't', description: 'Token budget' },
+    { name: 'brief', type: 'boolean', description: 'Minimal output' },
+    { name: 'full', type: 'boolean', description: 'Include full content' },
+    {
+      name: 'section',
+      type: 'string',
+      alias: 'S',
+      description: 'Filter by section name, number, or glob pattern',
+    },
+    {
+      name: 'sections',
+      type: 'boolean',
+      description: 'List available sections',
+    },
+    {
+      name: 'shallow',
+      type: 'boolean',
+      description: 'Exclude nested subsections when filtering',
+    },
+    jsonFlag,
+    prettyFlag,
+  ],
+}
+
+export const treeSchema: CommandSchema = {
+  name: 'tree',
+  flags: [jsonFlag, prettyFlag],
+}
+
+export const linksSchema: CommandSchema = {
+  name: 'links',
+  flags: [rootFlag, jsonFlag, prettyFlag],
+}
+
+export const backlinksSchema: CommandSchema = {
+  name: 'backlinks',
+  flags: [rootFlag, jsonFlag, prettyFlag],
+}
+
+export const statsSchema: CommandSchema = {
+  name: 'stats',
+  flags: [jsonFlag, prettyFlag],
+}
+
+// ============================================================================
+// Schema Registry
+// ============================================================================
+
+/**
+ * All command schemas indexed by command name
+ */
+export const commandSchemas: Record<string, CommandSchema> = {
+  index: indexSchema,
+  search: searchSchema,
+  context: contextSchema,
+  tree: treeSchema,
+  links: linksSchema,
+  backlinks: backlinksSchema,
+  stats: statsSchema,
+}
+
+/**
+ * Get schema for a command
+ */
+export const getCommandSchema = (
+  commandName: string,
+): CommandSchema | undefined => {
+  return commandSchemas[commandName]
+}
+
+/**
+ * Get all valid flag names for a command (both long and short forms)
+ */
+export const getValidFlags = (schema: CommandSchema): Set<string> => {
+  const flags = new Set<string>()
+  for (const spec of schema.flags) {
+    flags.add(`--${spec.name}`)
+    if (spec.alias) {
+      flags.add(`-${spec.alias}`)
+    }
+  }
+  return flags
+}
+
+/**
+ * Check if a flag takes a value for a given command
+ */
+export const flagTakesValue = (
+  schema: CommandSchema,
+  flag: string,
+): boolean => {
+  // Handle --flag=value syntax
+  if (flag.includes('=')) {
+    return false // Value is already embedded
+  }
+
+  for (const spec of schema.flags) {
+    if (
+      flag === `--${spec.name}` ||
+      (spec.alias && flag === `-${spec.alias}`)
+    ) {
+      return spec.type === 'string'
+    }
+  }
+  return false
+}
+
+/**
+ * Find the canonical name for a flag (for suggestions)
+ */
+export const getCanonicalFlagName = (
+  schema: CommandSchema,
+  flag: string,
+): string | undefined => {
+  for (const spec of schema.flags) {
+    if (
+      flag === `--${spec.name}` ||
+      (spec.alias && flag === `-${spec.alias}`)
+    ) {
+      return `--${spec.name}`
+    }
+  }
+  return undefined
+}

package/src/cli/help.ts

@@ -0,0 +1,386 @@
+/**
+ * Custom help system for mdcontext CLI
+ *
+ * Provides beautiful, useful help output that matches the quality of
+ * professional CLI tools like git and gh.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface CommandHelp {
+  description: string
+  usage: string
+  examples: string[]
+  options: { name: string; description: string }[]
+  notes?: string[]
+}
+
+// ============================================================================
+// Help Content
+// ============================================================================
+
+export const helpContent: Record<string, CommandHelp> = {
+  index: {
+    description: 'Index markdown files for fast searching',
+    usage: 'mdcontext index [path] [options]',
+    examples: [
+      'mdcontext index                    # Index current directory',
+      'mdcontext index docs/              # Index specific directory',
+      'mdcontext index --embed            # Include semantic embeddings',
+      'mdcontext index --watch            # Watch for file changes',
+      'mdcontext index --embed --watch    # Full setup with live updates',
+      'mdcontext index --force            # Rebuild from scratch',
+    ],
+    options: [
+      {
+        name: '-e, --embed',
+        description: 'Build semantic embeddings (enables AI-powered search)',
+      },
+      {
+        name: '--no-embed',
+        description: 'Skip the prompt to enable semantic search',
+      },
+      {
+        name: '-w, --watch',
+        description: 'Watch for changes and re-index automatically',
+      },
+      { name: '--force', description: 'Rebuild from scratch, ignoring cache' },
+      { name: '--json', description: 'Output results as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: [
+      'After indexing, prompts to enable semantic search (use --no-embed to skip).',
+      'Embedding requires OPENAI_API_KEY environment variable.',
+      'Index is stored in .mdcontext/ directory.',
+    ],
+  },
+  search: {
+    description: 'Search markdown content by meaning or heading pattern',
+    usage: 'mdcontext search [options] <query> [path]',
+    examples: [
+      'mdcontext search "auth"                    # Simple term search',
+      'mdcontext search "auth AND deploy"         # Both terms required',
+      'mdcontext search "error OR bug"            # Either term matches',
+      'mdcontext search "impl NOT test"           # Exclude "test"',
+      'mdcontext search "auth AND (error OR bug)" # Grouped expressions',
+      'mdcontext search \'"exact phrase"\'          # Exact phrase match',
+      'mdcontext search \'"context resumption" AND drift\'  # Phrase + boolean',
+      'mdcontext search -H "API.*"                # Regex on headings only',
+      'mdcontext search --mode keyword "auth"     # Force keyword mode',
+      'mdcontext search --mode semantic "auth"    # Force semantic mode',
+      'mdcontext search -n 5 "setup"              # Limit to 5 results',
+      'mdcontext search "config" docs/            # Search in specific directory',
+      '',
+      '# Context lines (like grep):',
+      'mdcontext search "checkpoint" -C 3         # 3 lines before AND after',
+      'mdcontext search "error" -B 2 -A 5         # 2 before, 5 after',
+    ],
+    options: [
+      {
+        name: '-k, --keyword',
+        description: 'Force keyword search (content text match)',
+      },
+      {
+        name: '-H, --heading-only',
+        description: 'Search headings only (not content)',
+      },
+      {
+        name: '-m, --mode <mode>',
+        description: 'Force search mode: semantic or keyword',
+      },
+      {
+        name: '-n, --limit <n>',
+        description: 'Maximum number of results (default: 10)',
+      },
+      {
+        name: '-C <n>',
+        description: 'Show N context lines before AND after each match',
+      },
+      {
+        name: '-B <n>',
+        description: 'Show N context lines before each match',
+      },
+      {
+        name: '-A <n>',
+        description: 'Show N context lines after each match',
+      },
+      {
+        name: '--threshold <n>',
+        description:
+          'Similarity threshold 0-1 for semantic search (default: 0.5)',
+      },
+      { name: '--json', description: 'Output results as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: [
+      'Auto-detects mode: semantic if embeddings exist, keyword otherwise.',
+      'Boolean operators: AND, OR, NOT (case-insensitive).',
+      'Quoted phrases match exactly: "context resumption".',
+      'Regex patterns (e.g., "API.*") always use keyword search.',
+      'Run "mdcontext index --embed" first for semantic search.',
+    ],
+  },
+  context: {
+    description: 'Get LLM-ready summary of markdown files',
+    usage: 'mdcontext context [options] <files>...',
+    examples: [
+      'mdcontext context README.md        # Summarize single file',
+      'mdcontext context *.md             # Summarize all markdown files',
+      'mdcontext context -t 1000 *.md     # Fit within 1000 token budget',
+      'mdcontext context --brief *.md     # Minimal output (headings only)',
+      'mdcontext context --full doc.md    # Include full content',
+      'mdcontext context *.md | pbcopy    # Copy to clipboard (macOS)',
+      '',
+      '# Section filtering:',
+      'mdcontext context doc.md --sections                # List available sections',
+      'mdcontext context doc.md --section "Setup"         # Extract by section name',
+      'mdcontext context doc.md --section "2.1"           # Extract by section number',
+      'mdcontext context doc.md --section "API*"          # Glob pattern matching',
+      'mdcontext context doc.md --section "Config" --shallow  # Top-level only',
+    ],
+    options: [
+      {
+        name: '-t, --tokens <n>',
+        description: 'Token budget for output (default: 2000)',
+      },
+      {
+        name: '--brief',
+        description: 'Minimal output (headings and key points only)',
+      },
+      {
+        name: '--full',
+        description: 'Include full content (no summarization)',
+      },
+      {
+        name: '--section <name>',
+        description:
+          'Extract specific section by name, number, or glob pattern',
+      },
+      {
+        name: '--sections',
+        description: 'List available sections with numbers and token counts',
+      },
+      {
+        name: '--shallow',
+        description: 'Exclude nested subsections when using --section',
+      },
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: [
+      'Token budget controls how much content is included.',
+      'Lower tokens = more aggressive summarization.',
+      'Output is formatted for direct use in LLM prompts.',
+      'Use --sections to discover section names before filtering.',
+    ],
+  },
+  tree: {
+    description: 'Show file tree or document outline',
+    usage: 'mdcontext tree [path] [options]',
+    examples: [
+      'mdcontext tree                     # List markdown files in current dir',
+      'mdcontext tree docs/               # List files in specific directory',
+      'mdcontext tree README.md           # Show document outline (headings)',
+      'mdcontext tree doc.md --json       # Outline as JSON',
+    ],
+    options: [
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: [
+      'Pass a directory to list markdown files.',
+      'Pass a file to show its heading structure with token counts.',
+    ],
+  },
+  links: {
+    description: 'Show what a file links to (outgoing links)',
+    usage: 'mdcontext links <file> [options]',
+    examples: [
+      'mdcontext links README.md          # Show outgoing links',
+      'mdcontext links doc.md --json      # Output as JSON',
+      'mdcontext links doc.md -r docs/    # Resolve links relative to docs/',
+    ],
+    options: [
+      {
+        name: '-r, --root <dir>',
+        description: 'Root directory for resolving relative links',
+      },
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+  },
+  backlinks: {
+    description: 'Show what links to a file (incoming links)',
+    usage: 'mdcontext backlinks <file> [options]',
+    examples: [
+      'mdcontext backlinks api.md         # What links to api.md?',
+      'mdcontext backlinks doc.md --json  # Output as JSON',
+      'mdcontext backlinks doc.md -r ./   # Resolve from current directory',
+    ],
+    options: [
+      {
+        name: '-r, --root <dir>',
+        description: 'Root directory for resolving relative links',
+      },
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: ['Requires index to exist. Run "mdcontext index" first.'],
+  },
+  stats: {
+    description: 'Show index statistics',
+    usage: 'mdcontext stats [path] [options]',
+    examples: [
+      'mdcontext stats                    # Show stats for current directory',
+      'mdcontext stats docs/              # Show stats for specific directory',
+      'mdcontext stats --json             # Output as JSON',
+    ],
+    options: [
+      { name: '--json', description: 'Output as JSON' },
+      { name: '--pretty', description: 'Pretty-print JSON output' },
+    ],
+    notes: ['Shows embedding count, dimensions, and cost if embeddings exist.'],
+  },
+}
+
+// ============================================================================
+// Help Rendering
+// ============================================================================
+
+/**
+ * Render beautiful subcommand help
+ */
+export const showSubcommandHelp = (command: string): void => {
+  const help = helpContent[command]
+  if (!help) {
+    console.log(`Unknown command: ${command}`)
+    console.log('Run "mdcontext --help" for available commands.')
+    process.exit(1)
+  }
+
+  // Header
+  console.log(`\n\x1b[1mmdcontext ${command}\x1b[0m - ${help.description}`)
+
+  // Usage
+  console.log(`\n\x1b[33mUSAGE\x1b[0m`)
+  console.log(`  ${help.usage}`)
+
+  // Examples
+  console.log(`\n\x1b[33mEXAMPLES\x1b[0m`)
+  for (const example of help.examples) {
+    console.log(`  ${example}`)
+  }
+
+  // Options
+  console.log(`\n\x1b[33mOPTIONS\x1b[0m`)
+  for (const opt of help.options) {
+    // Pad option name to 24 chars for alignment
+    const paddedName = opt.name.padEnd(24)
+    console.log(`  ${paddedName}${opt.description}`)
+  }
+
+  // Notes (if any)
+  if (help.notes && help.notes.length > 0) {
+    console.log(`\n\x1b[33mNOTES\x1b[0m`)
+    for (const note of help.notes) {
+      console.log(`  ${note}`)
+    }
+  }
+
+  console.log('')
+}
+
+/**
+ * Custom help output for main command - beautiful and useful
+ */
+export const showMainHelp = (): void => {
+  const help = `
+\x1b[1mmdcontext\x1b[0m - Token-efficient markdown analysis for LLMs
+
+\x1b[33mCOMMANDS\x1b[0m
+  index [path]              Index markdown files (default: .)
+  search <query> [path]     Search by meaning or structure
+  context <files>...        Get LLM-ready summary
+  tree [path]               Show files or document outline
+  links <file>              Show outgoing links
+  backlinks <file>          Show incoming links
+  stats [path]              Index statistics
+
+\x1b[33mEXAMPLES\x1b[0m
+  mdcontext tree                         # List all markdown files
+  mdcontext tree README.md               # Show document outline
+  mdcontext index                        # Index current directory
+  mdcontext index --embed                # Index with semantic embeddings
+  mdcontext search "auth"                # Simple term search
+  mdcontext search "auth AND deploy"     # Boolean AND (both required)
+  mdcontext search "error OR bug"        # Boolean OR (either matches)
+  mdcontext search '"exact phrase"'      # Quoted phrase (exact match)
+  mdcontext search "how to deploy"       # Semantic search (if embeddings exist)
+  mdcontext context README.md            # Summarize a file
+  mdcontext context *.md -t 2000         # Multi-file with token budget
+
+\x1b[33mWORKFLOWS\x1b[0m
+  \x1b[2m# Quick context for LLM\x1b[0m
+  mdcontext context README.md docs/*.md | pbcopy
+
+  \x1b[2m# Find relevant documentation\x1b[0m
+  mdcontext search "error handling"
+
+  \x1b[2m# Complex queries with boolean operators\x1b[0m
+  mdcontext search "auth AND (error OR exception) NOT test"
+
+  \x1b[2m# Explore a new codebase\x1b[0m
+  mdcontext tree && mdcontext stats
+
+  \x1b[2m# Build semantic search\x1b[0m
+  mdcontext index --embed && mdcontext search "authentication flow"
+
+\x1b[33mGLOBAL OPTIONS\x1b[0m
+  --json          Output as JSON
+  --pretty        Pretty-print JSON
+  --help, -h      Show help
+  --version, -v   Show version
+
+Run \x1b[36mmdcontext <command> --help\x1b[0m for command-specific options.
+`
+  console.log(help)
+}
+
+// ============================================================================
+// Help Detection
+// ============================================================================
+
+/**
+ * Check for subcommand help pattern: mdcontext <cmd> --help or mdcontext <cmd> -h
+ * Returns true if help was shown and we should exit
+ */
+export const checkSubcommandHelp = (): boolean => {
+  const args = process.argv.slice(2)
+  if (args.length < 2) return false
+
+  const command = args[0]
+  const hasHelpFlag = args.includes('--help') || args.includes('-h')
+
+  if (hasHelpFlag && command && helpContent[command]) {
+    showSubcommandHelp(command)
+    process.exit(0)
+  }
+
+  return false
+}
+
+/**
+ * Check if we should show main help
+ */
+export const shouldShowMainHelp = (): boolean => {
+  const args = process.argv.slice(2)
+  const showHelp =
+    args.length === 0 ||
+    args.includes('--help') ||
+    args.includes('-h') ||
+    (args.length === 1 && args[0] === 'help')
+
+  return showHelp && !args.some((a) => !a.startsWith('-') && a !== 'help')
+}

package/src/cli/index.ts

@@ -0,0 +1,9 @@
+/**
+ * CLI module barrel export
+ *
+ * Re-exports CLI utilities for programmatic use.
+ * The CLI entry point is in main.ts.
+ */
+
+// Currently no public exports - CLI is run directly via main.ts
+// Future: export shared utilities, command builders, etc.