arcfetch 3.0.0

package/README.md

@@ -0,0 +1,215 @@
+# arcfetch
+
+Fetch URLs, extract clean article content, and cache as markdown. Supports automatic JavaScript rendering fallback via Playwright (local or Docker).
+
+## Features
+
+- **Smart Fetching**: Simple HTTP first, automatic Playwright fallback for JS-heavy sites
+- **Quality Gates**: Configurable quality thresholds with automatic retry
+- **Docker Support**: Auto-launches Playwright in Docker when available
+- **Clean Markdown**: Mozilla Readability + Turndown for 90-95% token reduction
+- **Temp → Docs Workflow**: Cache to temp folder, promote to docs when ready
+- **CLI & MCP**: Available as command-line tool and MCP server
+
+## Installation
+
+```bash
+bun install
+```
+
+For Docker Playwright support (recommended):
+```bash
+docker pull mcr.microsoft.com/playwright:v1.40.0-jammy
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Fetch a URL
+arcfetch fetch https://example.com/article
+
+# List cached references
+arcfetch list
+
+# Promote to docs folder
+arcfetch promote REF-001
+
+# Delete a reference
+arcfetch delete REF-001
+```
+
+### MCP Server
+
+Add to your Claude Code MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "arcfetch": {
+      "command": "bun",
+      "args": ["run", "/path/to/arcfetch/index.ts"]
+    }
+  }
+}
+```
+
+## CLI Commands
+
+### fetch
+
+Fetch URL and save to temp folder.
+
+```bash
+arcfetch fetch <url> [options]
+
+Options:
+  -q, --query <text>      Search query (saved as metadata)
+  -o, --output <format>   Output: text, json, summary (default: text)
+  -v, --verbose           Show detailed output
+  --min-quality <n>       Minimum quality score 0-100 (default: 60)
+  --temp-dir <path>       Temp folder (default: .tmp)
+  --docs-dir <path>       Docs folder (default: docs/ai/references)
+  --playwright <mode>     Playwright mode: auto, local, docker
+```
+
+### list
+
+List all cached references.
+
+```bash
+arcfetch list [-o json]
+```
+
+### promote
+
+Move reference from temp to docs folder.
+
+```bash
+arcfetch promote <ref-id>
+```
+
+### delete
+
+Delete a cached reference.
+
+```bash
+arcfetch delete <ref-id>
+```
+
+### config
+
+Show current configuration.
+
+```bash
+arcfetch config
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `fetch_url` | Fetch URL with auto JS fallback, save to temp |
+| `list_cached` | List all cached references |
+| `promote_reference` | Move from temp to docs folder |
+| `delete_cached` | Delete a cached reference |
+
+## Configuration
+
+### Config File
+
+Create `arcfetch.config.json` in your project root:
+
+```json
+{
+  "quality": {
+    "minScore": 60,
+    "jsRetryThreshold": 85
+  },
+  "paths": {
+    "tempDir": ".tmp",
+    "docsDir": "docs/ai/references"
+  },
+  "playwright": {
+    "mode": "auto",
+    "dockerImage": "mcr.microsoft.com/playwright:v1.40.0-jammy",
+    "timeout": 30000
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+SOFETCH_MIN_SCORE=60
+SOFETCH_TEMP_DIR=.tmp
+SOFETCH_DOCS_DIR=docs/ai/references
+SOFETCH_PLAYWRIGHT_MODE=auto
+SOFETCH_DOCKER_IMAGE=mcr.microsoft.com/playwright:v1.40.0-jammy
+```
+
+## Quality Pipeline
+
+```
+URL → Simple Fetch → Quality Check
+                         │
+         ┌───────────────┼───────────────┐
+         ▼               ▼               ▼
+     Score ≥ 85      60-84           < 60
+         │               │               │
+         ▼               ▼               ▼
+       Save        Try Playwright   Try Playwright
+                   (if better)      (required)
+                         │               │
+                         ▼               ▼
+                   Compare &       Score ≥ 60?
+                   use best        Yes → Save
+                                   No → Error
+```
+
+## Playwright Modes
+
+| Mode | Description |
+|------|-------------|
+| `auto` | Use Docker if available, fall back to local |
+| `docker` | Docker only (fails if Docker unavailable) |
+| `local` | Local Playwright only (requires `bun install`) |
+
+## File Structure
+
+```
+.tmp/                          # Temporary cache (default)
+  REF-001-article-title.md
+  REF-002-another-article.md
+
+docs/ai/references/            # Permanent docs (after promote)
+  REF-001-article-title.md
+```
+
+## Examples
+
+### Fetch with custom quality threshold
+
+```bash
+arcfetch fetch https://spa-heavy-site.com --min-quality 70 --playwright docker
+```
+
+### Fetch and get JSON output
+
+```bash
+arcfetch fetch https://example.com -o json
+```
+
+### Use in scripts
+
+```bash
+# Get just the ref ID and path
+result=$(arcfetch fetch https://example.com -o summary)
+ref_id=$(echo $result | cut -d'|' -f1)
+filepath=$(echo $result | cut -d'|' -f2)
+```
+
+## License
+
+MIT

package/cli.ts

@@ -0,0 +1,455 @@
+#!/usr/bin/env bun
+
+import { loadConfig } from './src/config/index.js';
+import { fetchUrl, closeBrowser } from './src/core/pipeline.js';
+import { saveToTemp, listCached, promoteReference, deleteCached } from './src/core/cache.js';
+
+// ============================================================================
+// HELP
+// ============================================================================
+
+function showHelp(): void {
+  console.log(`
+Sofetch v3.0 - Fetch URLs and cache as clean markdown
+
+USAGE:
+    arcfetch <command> [options]
+
+COMMANDS:
+    fetch <url>       Fetch URL and save to temp folder
+    list              List all cached references
+    promote <ref-id>  Move reference from temp to docs folder
+    delete <ref-id>   Delete a cached reference
+    config            Show current configuration
+    help              Show this help message
+
+OPTIONS:
+    -q, --query <text>        Search query (saved as metadata)
+    -o, --output <format>     Output format (default: text)
+                              - text: Plain text (LLM-friendly)
+                              - json: Structured JSON
+                              - path: Just the filepath
+                              - summary: REF-ID|filepath
+    --pretty                  Human-friendly output with emojis
+    -v, --verbose             Show detailed output
+    --min-quality <n>         Minimum quality score 0-100 (default: 60)
+    --temp-dir <path>         Temp folder (default: .tmp)
+    --docs-dir <path>         Docs folder (default: docs/ai/references)
+    --playwright <mode>       Playwright mode: auto, local, docker
+
+EXAMPLES:
+    # Fetch a URL (plain output for LLMs)
+    arcfetch fetch https://example.com/article
+
+    # Fetch and get just the filepath
+    arcfetch fetch https://example.com -o path
+
+    # Fetch with human-friendly output
+    arcfetch fetch https://example.com --pretty
+
+    # Fetch with JSON output
+    arcfetch fetch https://example.com -o json
+
+    # List cached references
+    arcfetch list
+
+    # Promote to docs folder
+    arcfetch promote REF-001
+
+ENVIRONMENT VARIABLES:
+    SOFETCH_MIN_SCORE          Minimum quality score
+    SOFETCH_TEMP_DIR           Temp directory
+    SOFETCH_DOCS_DIR           Docs directory
+    SOFETCH_PLAYWRIGHT_MODE    Playwright mode (auto/local/docker)
+
+CONFIG FILE:
+    Place arcfetch.config.json in project root for persistent settings.
+`);
+}
+
+// ============================================================================
+// FETCH COMMAND
+// ============================================================================
+
+interface FetchOptions {
+  url: string;
+  query?: string;
+  output: 'text' | 'json' | 'summary' | 'path';
+  verbose: boolean;
+  pretty: boolean;
+  minQuality?: number;
+  tempDir?: string;
+  docsDir?: string;
+  playwrightMode?: 'auto' | 'local' | 'docker';
+}
+
+async function commandFetch(options: FetchOptions): Promise<void> {
+  const config = loadConfig({
+    minQuality: options.minQuality,
+    tempDir: options.tempDir,
+    docsDir: options.docsDir,
+    playwrightMode: options.playwrightMode,
+  });
+
+  if (options.verbose) {
+    console.error('🔧 Config:', JSON.stringify(config, null, 2));
+  }
+
+  // Fetch URL
+  const result = await fetchUrl(options.url, config, options.verbose);
+
+  // Close browser if it was used
+  await closeBrowser();
+
+  if (!result.success) {
+    if (options.output === 'json') {
+      console.log(
+        JSON.stringify(
+          {
+            success: false,
+            error: result.error,
+            suggestion: result.suggestion,
+            quality: result.quality,
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`Error: ${result.error}`);
+      if (result.suggestion) {
+        console.error(`Suggestion: ${result.suggestion}`);
+      }
+      if (result.quality) {
+        console.error(`Quality: ${result.quality.score}/100`);
+      }
+    }
+    process.exit(1);
+  }
+
+  // Save to temp
+  const saveResult = await saveToTemp(config, result.title!, options.url, result.markdown!, options.query);
+
+  // Small delay to ensure file is flushed to disk (Bun-specific issue)
+  await new Promise((resolve) => setTimeout(resolve, 100));
+
+  if (saveResult.error) {
+    if (options.output === 'json') {
+      console.log(JSON.stringify({ success: false, error: saveResult.error }, null, 2));
+    } else {
+      console.error(`Error: Save failed: ${saveResult.error}`);
+    }
+    process.exit(1);
+  }
+
+  // Output result
+  if (options.output === 'json') {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          refId: saveResult.refId,
+          title: result.title,
+          byline: result.byline,
+          siteName: result.siteName,
+          excerpt: result.excerpt,
+          url: options.url,
+          filepath: saveResult.filepath,
+          size: result.markdown!.length,
+          tokens: Math.round(result.markdown!.length / 4),
+          quality: result.quality?.score,
+          usedPlaywright: result.usedPlaywright,
+          playwrightReason: result.playwrightReason,
+          query: options.query,
+        },
+        null,
+        2
+      )
+    );
+  } else if (options.output === 'summary') {
+    console.log(`${saveResult.refId}|${saveResult.filepath}`);
+  } else if (options.output === 'path') {
+    console.log(saveResult.filepath);
+  } else if (options.pretty) {
+    // Pretty output with emojis (human-friendly)
+    console.log(`✅ Cached: ${saveResult.refId}\n`);
+    console.log(`**Title**: ${result.title}`);
+    if (result.byline) console.log(`**Author**: ${result.byline}`);
+    if (result.siteName) console.log(`**Source**: ${result.siteName}`);
+    if (result.excerpt) {
+      const excerpt = result.excerpt.slice(0, 150);
+      console.log(`**Summary**: ${excerpt}${result.excerpt.length > 150 ? '...' : ''}`);
+    }
+    console.log(`\n**Saved to**: ${saveResult.filepath}`);
+    console.log(`**Size**: ${result.markdown!.length} chars (~${Math.round(result.markdown!.length / 4)} tokens)`);
+    console.log(`**Quality**: ${result.quality?.score}/100`);
+    if (result.usedPlaywright) {
+      console.log(`**Playwright**: Yes (${result.playwrightReason})`);
+    }
+    console.log(`\n💡 To promote to docs: arcfetch promote ${saveResult.refId}`);
+  } else {
+    // Plain output (LLM-friendly, default)
+    console.log(`Cached: ${saveResult.refId}`);
+    console.log(`Title: ${result.title}`);
+    if (result.byline) console.log(`Author: ${result.byline}`);
+    if (result.siteName) console.log(`Source: ${result.siteName}`);
+    if (result.excerpt) {
+      const excerpt = result.excerpt.slice(0, 150);
+      console.log(`Summary: ${excerpt}${result.excerpt.length > 150 ? '...' : ''}`);
+    }
+    console.log(`Filepath: ${saveResult.filepath}`);
+    console.log(`Size: ${result.markdown!.length} chars (~${Math.round(result.markdown!.length / 4)} tokens)`);
+    console.log(`Quality: ${result.quality?.score}/100`);
+    if (result.usedPlaywright) {
+      console.log(`Playwright: Yes (${result.playwrightReason})`);
+    }
+  }
+}
+
+// ============================================================================
+// LIST COMMAND
+// ============================================================================
+
+async function commandList(output: 'text' | 'json', pretty: boolean): Promise<void> {
+  const config = loadConfig();
+  const result = listCached(config);
+
+  if (result.error) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+
+  if (output === 'json') {
+    console.log(JSON.stringify(result.references, null, 2));
+    return;
+  }
+
+  if (result.references.length === 0) {
+    console.log(`No cached references in ${config.paths.tempDir}/`);
+    return;
+  }
+
+  if (pretty) {
+    console.log(`📚 Cached references (${result.references.length}):\n`);
+    for (const ref of result.references) {
+      console.log(`${ref.refId} | ${ref.title.slice(0, 50)}${ref.title.length > 50 ? '...' : ''}`);
+      console.log(`   📅 ${ref.fetchedDate} | 📄 ${Math.round(ref.size / 1024)}KB`);
+      console.log(`   🔗 ${ref.url.slice(0, 60)}${ref.url.length > 60 ? '...' : ''}`);
+      console.log('');
+    }
+    console.log(`💡 To promote: arcfetch promote <ref-id>`);
+    console.log(`💡 To delete: arcfetch delete <ref-id>`);
+  } else {
+    console.log(`Cached references (${result.references.length}):\n`);
+    for (const ref of result.references) {
+      console.log(`${ref.refId} | ${ref.title.slice(0, 50)}${ref.title.length > 50 ? '...' : ''}`);
+      console.log(`  Date: ${ref.fetchedDate} | Size: ${Math.round(ref.size / 1024)}KB`);
+      console.log(`  URL: ${ref.url.slice(0, 60)}${ref.url.length > 60 ? '...' : ''}`);
+      console.log('');
+    }
+  }
+}
+
+// ============================================================================
+// PROMOTE COMMAND
+// ============================================================================
+
+async function commandPromote(refId: string, output: 'text' | 'json', pretty: boolean): Promise<void> {
+  const config = loadConfig();
+  const result = promoteReference(config, refId);
+
+  if (output === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.success) process.exit(1);
+    return;
+  }
+
+  if (!result.success) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+
+  if (pretty) {
+    console.log(`✅ Promoted ${refId}`);
+    console.log(`   From: ${result.fromPath}`);
+    console.log(`   To:   ${result.toPath}`);
+  } else {
+    console.log(`Promoted: ${refId}`);
+    console.log(`From: ${result.fromPath}`);
+    console.log(`To: ${result.toPath}`);
+  }
+}
+
+// ============================================================================
+// DELETE COMMAND
+// ============================================================================
+
+async function commandDelete(refId: string, output: 'text' | 'json', pretty: boolean): Promise<void> {
+  const config = loadConfig();
+  const result = deleteCached(config, refId);
+
+  if (output === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.success) process.exit(1);
+    return;
+  }
+
+  if (!result.success) {
+    console.error(`Error: ${result.error}`);
+    process.exit(1);
+  }
+
+  if (pretty) {
+    console.log(`✅ Deleted ${refId}`);
+    console.log(`   File: ${result.filepath}`);
+  } else {
+    console.log(`Deleted: ${refId}`);
+    console.log(`File: ${result.filepath}`);
+  }
+}
+
+// ============================================================================
+// CONFIG COMMAND
+// ============================================================================
+
+async function commandConfig(): Promise<void> {
+  const config = loadConfig();
+  console.log('Current configuration:\n');
+  console.log(JSON.stringify(config, null, 2));
+}
+
+// ============================================================================
+// ARGUMENT PARSING
+// ============================================================================
+
+interface ParsedOptions {
+  output: 'text' | 'json' | 'summary' | 'path';
+  verbose: boolean;
+  pretty: boolean;
+  query?: string;
+  minQuality?: number;
+  tempDir?: string;
+  docsDir?: string;
+  playwrightMode?: 'auto' | 'local' | 'docker';
+}
+
+function parseArgs(): { command: string; args: string[]; options: ParsedOptions } {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    return { command: 'help', args: [], options: { output: 'text', verbose: false, pretty: false } };
+  }
+
+  const command = args[0];
+  const options: ParsedOptions = {
+    output: 'text',
+    verbose: false,
+    pretty: false,
+  };
+  const positionalArgs: string[] = [];
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    const next = args[i + 1];
+
+    if (arg === '-q' || arg === '--query') {
+      options.query = next;
+      i++;
+    } else if (arg === '-o' || arg === '--output') {
+      if (next === 'text' || next === 'json' || next === 'summary' || next === 'path') {
+        options.output = next;
+      }
+      i++;
+    } else if (arg === '-v' || arg === '--verbose') {
+      options.verbose = true;
+    } else if (arg === '--pretty') {
+      options.pretty = true;
+    } else if (arg === '--min-quality') {
+      options.minQuality = parseInt(next, 10);
+      i++;
+    } else if (arg === '--temp-dir') {
+      options.tempDir = next;
+      i++;
+    } else if (arg === '--docs-dir') {
+      options.docsDir = next;
+      i++;
+    } else if (arg === '--playwright') {
+      if (next === 'auto' || next === 'local' || next === 'docker') {
+        options.playwrightMode = next;
+      }
+      i++;
+    } else if (arg === '-h' || arg === '--help') {
+      return { command: 'help', args: [], options: { output: 'text', verbose: false, pretty: false } };
+    } else if (!arg.startsWith('-')) {
+      positionalArgs.push(arg);
+    }
+  }
+
+  return { command, args: positionalArgs, options };
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+async function main(): Promise<void> {
+  const { command, args, options } = parseArgs();
+
+  try {
+    switch (command) {
+      case 'fetch':
+        if (args.length === 0) {
+          console.error('Error: URL required. Usage: arcfetch fetch <url>');
+          process.exit(1);
+        }
+        await commandFetch({
+          url: args[0],
+          query: options.query,
+          output: options.output,
+          verbose: options.verbose,
+          pretty: options.pretty,
+          minQuality: options.minQuality,
+          tempDir: options.tempDir,
+          docsDir: options.docsDir,
+          playwrightMode: options.playwrightMode,
+        });
+        break;
+
+      case 'list':
+        await commandList(options.output === 'json' ? 'json' : 'text', options.pretty);
+        break;
+
+      case 'promote':
+        if (args.length === 0) {
+          console.error('Error: Reference ID required. Usage: arcfetch promote <ref-id>');
+          process.exit(1);
+        }
+        await commandPromote(args[0], options.output === 'json' ? 'json' : 'text', options.pretty);
+        break;
+
+      case 'delete':
+        if (args.length === 0) {
+          console.error('Error: Reference ID required. Usage: arcfetch delete <ref-id>');
+          process.exit(1);
+        }
+        await commandDelete(args[0], options.output === 'json' ? 'json' : 'text', options.pretty);
+        break;
+
+      case 'config':
+        await commandConfig();
+        break;
+
+      default:
+        showHelp();
+        break;
+    }
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Unexpected error:', err);
+  process.exit(1);
+});