@echofiles/echo-pdf 0.5.0 → 0.7.0

package/bin/echo-pdf.js

@@ -1,42 +1,34 @@
 #!/usr/bin/env node
-import { spawn } from "node:child_process"
 import fs from "node:fs"
 import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { downloadFile, postJson, prepareArgsWithLocalUploads, uploadFile, withUploadedLocalFile } from "./lib/http.js"
-import { runMcpStdio } from "./lib/mcp-stdio.js"
 
 const CONFIG_DIR = path.join(os.homedir(), ".config", "echo-pdf-cli")
 const CONFIG_FILE = path.join(CONFIG_DIR, "config.json")
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const PROJECT_CONFIG_FILE = path.resolve(__dirname, "../echo-pdf.config.json")
 const PROJECT_CONFIG = JSON.parse(fs.readFileSync(PROJECT_CONFIG_FILE, "utf-8"))
-const PROVIDER_ENTRIES = Object.entries(PROJECT_CONFIG.providers || {})
-const PROVIDER_ALIASES = PROVIDER_ENTRIES.map(([alias]) => alias)
-const PROVIDER_ALIAS_BY_TYPE = new Map(
-  PROVIDER_ENTRIES.map(([alias, provider]) => [provider.type, alias])
-)
-const PROVIDER_SET_NAMES = Array.from(
-  new Set(PROVIDER_ENTRIES.flatMap(([alias, provider]) => [alias, provider.type]))
-)
 const PROJECT_DEFAULT_MODEL = String(PROJECT_CONFIG.agent?.defaultModel || "").trim()
-const DEFAULT_WORKER_NAME = process.env.ECHO_PDF_WORKER_NAME || PROJECT_CONFIG.service?.name || "echo-pdf"
-const DEFAULT_SERVICE_URL = process.env.ECHO_PDF_SERVICE_URL || `https://${DEFAULT_WORKER_NAME}.echofilesai.workers.dev`
-const DEFAULT_MCP_HEADER = process.env.ECHO_PDF_MCP_HEADER?.trim() || PROJECT_CONFIG.mcp?.authHeader || "x-mcp-key"
+
+const getProviderEntries = () => Object.entries(PROJECT_CONFIG.providers || {})
+const getProviderAliases = () => getProviderEntries().map(([alias]) => alias)
+const getProviderAliasByType = () => new Map(getProviderEntries().map(([alias, provider]) => [provider.type, alias]))
+const getProviderSetNames = () => Array.from(new Set(getProviderEntries().flatMap(([alias, provider]) => [alias, provider.type])))
 
 const emptyProviders = () =>
-  Object.fromEntries(PROVIDER_ALIASES.map((providerAlias) => [providerAlias, { apiKey: "" }]))
+  Object.fromEntries(getProviderAliases().map((providerAlias) => [providerAlias, { apiKey: "" }]))
 
 const resolveProviderAliasInput = (input) => {
   if (typeof input !== "string" || input.trim().length === 0) {
     throw new Error("provider is required")
   }
   const raw = input.trim()
-  if (PROVIDER_ALIASES.includes(raw)) return raw
-  const fromType = PROVIDER_ALIAS_BY_TYPE.get(raw)
+  const providerAliases = getProviderAliases()
+  if (providerAliases.includes(raw)) return raw
+  const fromType = getProviderAliasByType().get(raw)
   if (fromType) return fromType
-  throw new Error(`provider must be one of: ${PROVIDER_SET_NAMES.join(", ")}`)
+  throw new Error(`provider must be one of: ${getProviderSetNames().join(", ")}`)
 }
 
 function resolveDefaultProviderAlias() {
@@ -44,13 +36,12 @@ function resolveDefaultProviderAlias() {
   if (typeof configured === "string" && configured.trim().length > 0) {
     return resolveProviderAliasInput(configured.trim())
   }
-  return PROVIDER_ALIASES[0] || "openai"
+  return getProviderAliases()[0] || "openai"
 }
 
 const DEFAULT_PROVIDER_ALIAS = resolveDefaultProviderAlias()
 
 const defaultConfig = () => ({
-  serviceUrl: DEFAULT_SERVICE_URL,
   profile: "default",
   profiles: {
     default: {
@@ -68,56 +59,11 @@ const ensureConfig = () => {
   }
 }
 
-const loadConfig = () => {
-  ensureConfig()
-  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"))
-  if (!config.profiles || typeof config.profiles !== "object") {
-    config.profiles = {}
-  }
-  if (typeof config.profile !== "string" || !config.profile) {
-    config.profile = "default"
-  }
-  const profile = getProfile(config, config.profile)
-  if (typeof profile.defaultProvider !== "string" || !profile.defaultProvider) {
-    profile.defaultProvider = DEFAULT_PROVIDER_ALIAS
-  }
-  if (!profile.providers || typeof profile.providers !== "object") {
-    profile.providers = emptyProviders()
-  }
-  for (const providerAlias of PROVIDER_ALIASES) {
-    if (!profile.providers[providerAlias] || typeof profile.providers[providerAlias] !== "object") {
-      profile.providers[providerAlias] = { apiKey: "" }
-    }
-  }
-  if (!profile.models || typeof profile.models !== "object") {
-    profile.models = {}
-  }
-  saveConfig(config)
-  return config
-}
-
 const saveConfig = (config) => {
   fs.mkdirSync(CONFIG_DIR, { recursive: true })
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2))
 }
 
-const parseFlags = (args) => {
-  const flags = {}
-  for (let i = 0; i < args.length; i += 1) {
-    const token = args[i]
-    if (!token?.startsWith("--")) continue
-    const key = token.slice(2)
-    const next = args[i + 1]
-    if (!next || next.startsWith("--")) {
-      flags[key] = true
-    } else {
-      flags[key] = next
-      i += 1
-    }
-  }
-  return flags
-}
-
 const getProfile = (config, name) => {
   const profileName = name || config.profile || "default"
   if (!config.profiles[profileName]) {
@@ -129,7 +75,7 @@ const getProfile = (config, name) => {
   }
   const profile = config.profiles[profileName]
   if (!profile.providers || typeof profile.providers !== "object") profile.providers = {}
-  for (const providerAlias of PROVIDER_ALIASES) {
+  for (const providerAlias of getProviderAliases()) {
     if (!profile.providers[providerAlias] || typeof profile.providers[providerAlias] !== "object") {
       profile.providers[providerAlias] = { apiKey: "" }
     }
@@ -141,6 +87,33 @@ const getProfile = (config, name) => {
   return profile
 }
 
+const loadConfig = () => {
+  ensureConfig()
+  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, "utf-8"))
+  if (!config.profiles || typeof config.profiles !== "object") config.profiles = {}
+  if (typeof config.profile !== "string" || !config.profile) config.profile = "default"
+  getProfile(config, config.profile)
+  saveConfig(config)
+  return config
+}
+
+const parseFlags = (args) => {
+  const flags = {}
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i]
+    if (!token?.startsWith("--")) continue
+    const key = token.slice(2)
+    const next = args[i + 1]
+    if (typeof next !== "string" || next.startsWith("--")) {
+      flags[key] = true
+    } else {
+      flags[key] = next
+      i += 1
+    }
+  }
+  return flags
+}
+
 const getProfileName = (config, profileName) => profileName || config.profile || "default"
 
 const resolveProviderAlias = (profile, explicitProvider) =>
@@ -154,10 +127,29 @@ const resolveDefaultModel = (profile, providerAlias) => {
   return PROJECT_DEFAULT_MODEL
 }
 
+const readEnvApiKey = (providerAlias) => {
+  const providerConfig = PROJECT_CONFIG.providers?.[providerAlias]
+  const keyName = providerConfig?.apiKeyEnv
+  if (typeof keyName !== "string" || keyName.trim().length === 0) return ""
+  const read = (name) => {
+    const value = process.env[name]
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : ""
+  }
+  const direct = read(keyName)
+  if (direct) return direct
+  if (keyName.endsWith("_API_KEY")) {
+    return read(keyName.replace(/_API_KEY$/, "_KEY"))
+  }
+  if (keyName.endsWith("_KEY")) {
+    return read(keyName.replace(/_KEY$/, "_API_KEY"))
+  }
+  return ""
+}
+
 const buildProviderApiKeys = (config, profileName) => {
   const profile = getProfile(config, profileName)
   const providerApiKeys = {}
-  for (const [providerAlias, providerConfig] of PROVIDER_ENTRIES) {
+  for (const [providerAlias, providerConfig] of getProviderEntries()) {
     const apiKey = profile.providers?.[providerAlias]?.apiKey || profile.providers?.[providerConfig.type]?.apiKey || ""
     providerApiKeys[providerAlias] = apiKey
     providerApiKeys[providerConfig.type] = apiKey
@@ -165,165 +157,41 @@ const buildProviderApiKeys = (config, profileName) => {
   return providerApiKeys
 }
 
-const print = (data) => {
-  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
-}
-
-const buildMcpHeaders = () => {
-  const token = process.env.ECHO_PDF_MCP_KEY?.trim()
-  if (!token) return {}
-  return { [DEFAULT_MCP_HEADER]: token }
-}
-
-const buildModelsRequest = (provider, providerApiKeys) => ({ provider, providerApiKeys })
-
-const buildToolCallRequest = (input) => ({
-  name: input.tool,
-  arguments: input.args,
-  provider: input.provider,
-  model: input.model,
-  providerApiKeys: input.providerApiKeys,
-})
-
-const buildMcpRequest = (id, method, params = {}) => ({
-  jsonrpc: "2.0",
-  id,
-  method,
-  params,
-})
-
-const runDevServer = (port, host) => {
-  const wranglerBin = path.resolve(__dirname, "../node_modules/.bin/wrangler")
-  const wranglerArgs = ["dev", "--port", String(port), "--ip", host]
-  const cmd = fs.existsSync(wranglerBin) ? wranglerBin : "npx"
-  const args = fs.existsSync(wranglerBin) ? wranglerArgs : ["-y", "wrangler", ...wranglerArgs]
-  const child = spawn(cmd, args, {
-    stdio: "inherit",
-    env: process.env,
-    cwd: process.cwd(),
-  })
-  child.on("exit", (code, signal) => {
-    if (signal) process.kill(process.pid, signal)
-    process.exit(code ?? 0)
-  })
-}
-
-const printLocalServiceHints = (host, port) => {
-  const resolvedHost = host === "0.0.0.0" ? "127.0.0.1" : host
-  const baseUrl = `http://${resolvedHost}:${port}`
-  const mcpUrl = `${baseUrl}/mcp`
-  process.stdout.write(`\nLocal component endpoints:\n`)
-  process.stdout.write(`  ECHO_PDF_BASE_URL=${baseUrl}\n`)
-  process.stdout.write(`  ECHO_PDF_MCP_URL=${mcpUrl}\n`)
-  process.stdout.write(`\nExport snippet:\n`)
-  process.stdout.write(`  export ECHO_PDF_BASE_URL=${baseUrl}\n`)
-  process.stdout.write(`  export ECHO_PDF_MCP_URL=${mcpUrl}\n\n`)
-}
-
-const runMcpStdioCommand = async (serviceUrlOverride) => {
+const resolveLocalSemanticContext = (flags) => {
   const config = loadConfig()
-  const serviceUrl = typeof serviceUrlOverride === "string" && serviceUrlOverride.trim().length > 0
-    ? serviceUrlOverride.trim()
-    : config.serviceUrl
-  await runMcpStdio({
-    serviceUrl,
-    headers: buildMcpHeaders(),
-    postJson,
-    withUploadedLocalFile,
-  })
-}
-
-const parseConfigValue = (raw, type = "auto") => {
-  if (type === "string") return String(raw)
-  if (type === "number") {
-    const n = Number(raw)
-    if (!Number.isFinite(n)) throw new Error(`Invalid number: ${raw}`)
-    return n
-  }
-  if (type === "boolean") {
-    if (raw === "true") return true
-    if (raw === "false") return false
-    throw new Error(`Invalid boolean: ${raw}`)
-  }
-  if (type === "json") {
-    return JSON.parse(raw)
-  }
-  if (raw === "true") return true
-  if (raw === "false") return false
-  if (raw === "null") return null
-  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw)
-  if ((raw.startsWith("{") && raw.endsWith("}")) || (raw.startsWith("[") && raw.endsWith("]"))) {
-    try {
-      return JSON.parse(raw)
-    } catch {
-      return raw
-    }
-  }
-  return raw
-}
-
-const hasPath = (obj, dottedPath) => {
-  const parts = dottedPath.split(".").filter(Boolean)
-  let cur = obj
-  for (const part of parts) {
-    if (!cur || typeof cur !== "object" || !(part in cur)) return false
-    cur = cur[part]
-  }
-  return true
-}
-
-const setPath = (obj, dottedPath, value) => {
-  const parts = dottedPath.split(".").filter(Boolean)
-  if (parts.length === 0) throw new Error("config key is required")
-  let cur = obj
-  for (let i = 0; i < parts.length - 1; i += 1) {
-    const part = parts[i]
-    if (!cur[part] || typeof cur[part] !== "object" || Array.isArray(cur[part])) {
-      cur[part] = {}
-    }
-    cur = cur[part]
+  const profileName = getProfileName(config, flags.profile)
+  const profile = getProfile(config, profileName)
+  const provider = resolveProviderAlias(profile, flags.provider)
+  const model = typeof flags.model === "string" ? flags.model.trim() : resolveDefaultModel(profile, provider)
+  if (!model) {
+    throw new Error(
+      [
+        `semantic requires a configured model for provider "${provider}".`,
+        `Pass \`--model <model-id>\`, or run \`echo-pdf model set --provider ${provider} --model <model-id>${profileName ? ` --profile ${profileName}` : ""}\`.`,
+      ].join(" ")
+    )
   }
-  cur[parts[parts.length - 1]] = value
-}
-
-const readDevVarsConfigJson = (devVarsPath) => {
-  if (!fs.existsSync(devVarsPath)) return null
-  const lines = fs.readFileSync(devVarsPath, "utf-8").split(/\r?\n/)
-  for (const line of lines) {
-    if (line.startsWith("ECHO_PDF_CONFIG_JSON=")) {
-      const raw = line.slice("ECHO_PDF_CONFIG_JSON=".length).trim()
-      if (!raw) return null
-      return JSON.parse(raw)
-    }
+  const providerApiKeys = buildProviderApiKeys(config, profileName)
+  const configuredApiKey = typeof providerApiKeys[provider] === "string" ? providerApiKeys[provider].trim() : ""
+  const apiKeyEnv = PROJECT_CONFIG.providers?.[provider]?.apiKeyEnv || ""
+  if (apiKeyEnv && !configuredApiKey && !readEnvApiKey(provider)) {
+    throw new Error(
+      [
+        `semantic requires an API key for provider "${provider}".`,
+        `Run \`echo-pdf provider set --provider ${provider} --api-key <KEY>${profileName ? ` --profile ${profileName}` : ""}\``,
+        `or export \`${apiKeyEnv}\` before running the VL-first semantic path.`,
+      ].join(" ")
+    )
   }
-  return null
+  return { provider, model, providerApiKeys }
 }
 
-const writeDevVarsConfigJson = (devVarsPath, configJson) => {
-  const serialized = JSON.stringify(configJson)
-  const nextLine = `ECHO_PDF_CONFIG_JSON=${serialized}`
-  let lines = []
-  if (fs.existsSync(devVarsPath)) {
-    lines = fs.readFileSync(devVarsPath, "utf-8").split(/\r?\n/)
-    let replaced = false
-    lines = lines.map((line) => {
-      if (line.startsWith("ECHO_PDF_CONFIG_JSON=")) {
-        replaced = true
-        return nextLine
-      }
-      return line
-    })
-    if (!replaced) {
-      if (lines.length > 0 && lines[lines.length - 1].trim().length !== 0) lines.push("")
-      lines.push(nextLine)
-    }
-  } else {
-    lines = [nextLine]
-  }
-  fs.writeFileSync(devVarsPath, lines.join("\n"))
+const print = (data) => {
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`)
 }
 
 const LOCAL_DOCUMENT_DIST_ENTRY = new URL("../dist/local/index.js", import.meta.url)
+const LOCAL_DOCUMENT_DIST_PATH = fileURLToPath(LOCAL_DOCUMENT_DIST_ENTRY)
 const LOCAL_DOCUMENT_SOURCE_ENTRY = new URL("../src/local/index.ts", import.meta.url)
 const IS_BUN_RUNTIME = typeof process.versions?.bun === "string"
 const SHOULD_PREFER_SOURCE_DOCUMENT_API = process.env.ECHO_PDF_SOURCE_DEV === "1"
@@ -334,45 +202,54 @@ const loadLocalDocumentApi = async () => {
       return import(LOCAL_DOCUMENT_SOURCE_ENTRY.href)
     }
     throw new Error(
-      "Source-checkout document dev mode requires Bun and src/local/index.ts. " +
-      "Use `npm run document:dev -- <command> ...` from a source checkout."
+      "Internal source-checkout CLI dev mode requires Bun and src/local/index.ts. " +
+      "Use `npm run cli:dev -- <primitive> ...` only from a source checkout."
     )
   }
-  try {
-    return await import(LOCAL_DOCUMENT_DIST_ENTRY.href)
-  } catch (error) {
-    const code = error && typeof error === "object" ? error.code : ""
-    if (code === "ERR_MODULE_NOT_FOUND") {
-      throw new Error(
-        "Local document commands require built artifacts in a source checkout. " +
-        "Run `npm run build` first, use `npm run document:dev -- <command> ...` in a source checkout, or install the published package."
-      )
-    }
-    throw error
+  if (!fs.existsSync(LOCAL_DOCUMENT_DIST_PATH)) {
+    throw new Error(
+      "Local primitive commands require built artifacts in a source checkout. " +
+      "Run `npm run build` first, use the internal `npm run cli:dev -- <primitive> ...` path in this repo, or install the published package."
+    )
   }
+  return import(LOCAL_DOCUMENT_DIST_ENTRY.href)
 }
 
-const LOCAL_PRIMITIVE_COMMANDS = ["document", "structure", "semantic", "page", "render", "ocr"]
-const LEGACY_DOCUMENT_SUBCOMMANDS = ["index", "get", "structure", "semantic", "page", "render", "ocr"]
+const LOCAL_PRIMITIVE_COMMANDS = ["document", "structure", "semantic", "page", "render"]
+const REMOVED_DOCUMENT_ALIAS_TO_PRIMITIVE = {
+  index: "document",
+  get: "document",
+  structure: "structure",
+  semantic: "semantic",
+  page: "page",
+  render: "render",
+}
 
-const isLegacyDocumentSubcommand = (value) => typeof value === "string" && LEGACY_DOCUMENT_SUBCOMMANDS.includes(value)
+const isRemovedDocumentAlias = (value) =>
+  typeof value === "string" && Object.hasOwn(REMOVED_DOCUMENT_ALIAS_TO_PRIMITIVE, value)
+
+const removedDocumentAliasMessage = (alias) => {
+  const primitive = REMOVED_DOCUMENT_ALIAS_TO_PRIMITIVE[alias]
+  return `Legacy \`document ${alias}\` was removed. Use \`echo-pdf ${primitive} <file.pdf>\` instead.`
+}
 
 const readDocumentPrimitiveArgs = (command, subcommand, rest) => {
-  if (command === "document" && isLegacyDocumentSubcommand(subcommand)) {
-    const primitive = subcommand === "index" || subcommand === "get" ? "document" : subcommand
+  if (command === "document") {
+    if (isRemovedDocumentAlias(subcommand) && typeof rest[0] === "string" && !rest[0].startsWith("--")) {
+      throw new Error(removedDocumentAliasMessage(subcommand))
+    }
     return {
-      primitive,
-      pdfPath: rest[0],
+      primitive: "document",
+      pdfPath: subcommand,
     }
   }
   return {
     primitive: command,
-    pdfPath: command === "document" ? subcommand : rest[0],
+    pdfPath: rest[0],
   }
 }
 
 const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
-  const local = await loadLocalDocumentApi()
   const { primitive, pdfPath } = readDocumentPrimitiveArgs(command, subcommand, rest)
   const workspaceDir = typeof flags.workspace === "string" ? flags.workspace : undefined
   const forceRefresh = flags["force-refresh"] === true
@@ -383,26 +260,28 @@ const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
   }
 
   if (primitive === "document") {
-    const data = await local.get_document({ pdfPath, workspaceDir, forceRefresh })
-    print(data)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_document({ pdfPath, workspaceDir, forceRefresh }))
     return
   }
 
   if (primitive === "structure") {
-    const data = await local.get_document_structure({ pdfPath, workspaceDir, forceRefresh })
-    print(data)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_document_structure({ pdfPath, workspaceDir, forceRefresh }))
     return
   }
 
   if (primitive === "semantic") {
-    const data = await local.get_semantic_document_structure({
+    const semanticContext = resolveLocalSemanticContext(flags)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_semantic_document_structure({
       pdfPath,
       workspaceDir,
       forceRefresh,
-      provider: typeof flags.provider === "string" ? flags.provider : undefined,
-      model: typeof flags.model === "string" ? flags.model : undefined,
-    })
-    print(data)
+      provider: semanticContext.provider,
+      model: semanticContext.model,
+      providerApiKeys: semanticContext.providerApiKeys,
+    }))
     return
   }
 
@@ -412,29 +291,14 @@ const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
   }
 
   if (primitive === "page") {
-    const data = await local.get_page_content({ pdfPath, workspaceDir, forceRefresh, pageNumber })
-    print(data)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_page_content({ pdfPath, workspaceDir, forceRefresh, pageNumber }))
     return
   }
 
   if (primitive === "render") {
-    const data = await local.get_page_render({ pdfPath, workspaceDir, forceRefresh, pageNumber, renderScale })
-    print(data)
-    return
-  }
-
-  if (primitive === "ocr") {
-    const data = await local.get_page_ocr({
-      pdfPath,
-      workspaceDir,
-      forceRefresh,
-      pageNumber,
-      renderScale,
-      provider: typeof flags.provider === "string" ? flags.provider : undefined,
-      model: typeof flags.model === "string" ? flags.model : undefined,
-      prompt: typeof flags.prompt === "string" ? flags.prompt : undefined,
-    })
-    print(data)
+    const local = await loadLocalDocumentApi()
+    print(await local.get_page_render({ pdfPath, workspaceDir, forceRefresh, pageNumber, renderScale }))
     return
   }
 
@@ -443,114 +307,23 @@ const runLocalPrimitiveCommand = async (command, subcommand, rest, flags) => {
 
 const usage = () => {
   process.stdout.write(`echo-pdf CLI\n\n`)
-  process.stdout.write(`Commands:\n`)
+  process.stdout.write(`Primary local primitive commands:\n`)
   process.stdout.write(`  document <file.pdf> [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  structure <file.pdf> [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  semantic <file.pdf> [--provider alias] [--model model] [--workspace DIR] [--force-refresh]\n`)
+  process.stdout.write(`  semantic <file.pdf> [--provider alias] [--model model] [--profile name] [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  page <file.pdf> --page <N> [--workspace DIR] [--force-refresh]\n`)
   process.stdout.write(`  render <file.pdf> --page <N> [--scale N] [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  ocr <file.pdf> --page <N> [--scale N] [--provider alias] [--model model] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`\nCompatibility / existing service commands:\n`)
-  process.stdout.write(`  init [--service-url URL]\n`)
-  process.stdout.write(`  dev [--port 8788] [--host 127.0.0.1]\n`)
-  process.stdout.write(`  provider set --provider <${PROVIDER_SET_NAMES.join("|")}> --api-key <KEY> [--profile name]\n`)
-  process.stdout.write(`  provider use --provider <${PROVIDER_ALIASES.join("|")}> [--profile name]\n`)
+  process.stdout.write(`\nLocal config commands:\n`)
+  process.stdout.write(`  provider set --provider <${getProviderSetNames().join("|")}> --api-key <KEY> [--profile name]\n`)
+  process.stdout.write(`  provider use --provider <${getProviderAliases().join("|")}> [--profile name]\n`)
   process.stdout.write(`  provider list [--profile name]\n`)
-  process.stdout.write(`  models [--provider alias] [--profile name]\n`)
-  process.stdout.write(`  config set --key <dotted.path> --value <value> [--type auto|string|number|boolean|json] [--dev-vars .dev.vars]\n`)
   process.stdout.write(`  model set --model <model-id> [--provider alias] [--profile name]\n`)
   process.stdout.write(`  model get [--provider alias] [--profile name]\n`)
   process.stdout.write(`  model list [--profile name]\n`)
-  process.stdout.write(`  tools\n`)
-  process.stdout.write(`  call --tool <name> --args '<json>' [--provider alias] [--model model] [--profile name] [--auto-upload]\n`)
-  process.stdout.write(`  document get <file.pdf> [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  document structure <file.pdf> [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  document semantic <file.pdf> [--provider alias] [--model model] [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  document page <file.pdf> --page <N> [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  document render <file.pdf> --page <N> [--scale N] [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  document ocr <file.pdf> --page <N> [--scale N] [--provider alias] [--model model] [--prompt text] [--workspace DIR] [--force-refresh]\n`)
-  process.stdout.write(`  file upload <local.pdf>\n`)
-  process.stdout.write(`  file get --file-id <id> --out <path>\n`)
-  process.stdout.write(`  mcp initialize\n`)
-  process.stdout.write(`  mcp tools\n`)
-  process.stdout.write(`  mcp call --tool <name> --args '<json>'\n`)
-  process.stdout.write(`  mcp-stdio [--service-url URL]\n`)
-  process.stdout.write(`  mcp stdio\n`)
-  process.stdout.write(`  setup add <claude-desktop|claude-code|cursor|cline|windsurf|gemini|json>\n`)
-}
-
-const setupSnippet = (tool, serviceUrl, mode = "http") => {
-  if (mode === "stdio") {
-    return {
-      mcpServers: {
-        "echo-pdf": {
-          command: "echo-pdf",
-          args: ["mcp-stdio"],
-          env: {
-            ECHO_PDF_SERVICE_URL: serviceUrl,
-          },
-        },
-      },
-    }
-  }
-  const transport = {
-    type: "streamable-http",
-    url: `${serviceUrl}/mcp`,
-  }
-  if (tool === "json") {
-    return {
-      mcpServers: {
-        "echo-pdf": transport,
-      },
-    }
-  }
-  if (tool === "claude-desktop") {
-    return {
-      file: "claude_desktop_config.json",
-      snippet: {
-        mcpServers: {
-          "echo-pdf": transport,
-        },
-      },
-    }
-  }
-  if (tool === "cursor") {
-    return {
-      file: "~/.cursor/mcp.json",
-      snippet: {
-        mcpServers: {
-          "echo-pdf": transport,
-        },
-      },
-    }
-  }
-  if (tool === "cline") {
-    return {
-      file: "~/.cline/mcp_settings.json",
-      snippet: {
-        mcpServers: {
-          "echo-pdf": transport,
-        },
-      },
-    }
-  }
-  if (tool === "windsurf") {
-    return {
-      file: "~/.codeium/windsurf/mcp_config.json",
-      snippet: {
-        mcpServers: {
-          "echo-pdf": transport,
-        },
-      },
-    }
-  }
-  if (tool === "claude-code" || tool === "gemini") {
-    return {
-      note: "If your tool does not support streamable-http directly, use an HTTP-to-stdio MCP bridge (for example mcp-remote) and point it to /mcp.",
-      url: `${serviceUrl}/mcp`,
-    }
-  }
-  throw new Error(`Unsupported tool: ${tool}`)
+  process.stdout.write(`\nLocal LLM example (no auth):\n`)
+  process.stdout.write(`  echo-pdf provider set --provider ollama --api-key \"\"\n`)
+  process.stdout.write(`  echo-pdf model set --provider ollama --model llava:13b\n`)
+  process.stdout.write(`  echo-pdf semantic ./sample.pdf --provider ollama\n`)
 }
 
 const main = async () => {
@@ -563,34 +336,16 @@ const main = async () => {
   const [command, ...raw] = argv
   let subcommand = ""
   let rest = raw
-  if (["provider", "mcp", "setup", "model", "config", "document"].includes(command)) {
+  if (["provider", "model", "document"].includes(command)) {
     subcommand = raw[0] || ""
     rest = raw.slice(1)
   }
   const flags = parseFlags(rest)
 
-  if (command === "init") {
-    const config = loadConfig()
-    if (typeof flags["service-url"] === "string") {
-      config.serviceUrl = flags["service-url"]
-      saveConfig(config)
-    }
-    print({ ok: true, configFile: CONFIG_FILE, serviceUrl: config.serviceUrl })
-    return
-  }
-
-  if (command === "dev") {
-    const port = typeof flags.port === "string" ? Number(flags.port) : 8788
-    const host = typeof flags.host === "string" ? flags.host : "127.0.0.1"
-    if (!Number.isFinite(port) || port <= 0) throw new Error("dev --port must be positive number")
-    printLocalServiceHints(host, Math.floor(port))
-    runDevServer(Math.floor(port), host)
-    return
-  }
-
-  if (command === "mcp-stdio") {
-    await runMcpStdioCommand(typeof flags["service-url"] === "string" ? flags["service-url"] : undefined)
-    return
+  if (command === "ocr") {
+    throw new Error(
+      "`echo-pdf ocr` was removed from the first-class CLI surface. OCR is migration-only and no longer a supported primary command."
+    )
   }
 
   if (command === "provider" && subcommand === "set") {
@@ -633,45 +388,6 @@ const main = async () => {
     return
   }
 
-  if (command === "models") {
-    const config = loadConfig()
-    const profileName = getProfileName(config, flags.profile)
-    const profile = getProfile(config, profileName)
-    const provider = flags.provider ? resolveProviderAliasInput(flags.provider) : resolveProviderAlias(profile, flags.provider)
-    const providerApiKeys = buildProviderApiKeys(config, profileName)
-    const data = await postJson(`${config.serviceUrl}/providers/models`, buildModelsRequest(provider, providerApiKeys))
-    print(data)
-    return
-  }
-
-  if (command === "config" && subcommand === "set") {
-    const key = flags.key
-    const rawValue = flags.value
-    if (typeof key !== "string" || key.trim().length === 0) {
-      throw new Error("config set requires --key")
-    }
-    if (typeof rawValue !== "string") {
-      throw new Error("config set requires --value")
-    }
-    const type = typeof flags.type === "string" ? flags.type : "auto"
-    if (!["auto", "string", "number", "boolean", "json"].includes(type)) {
-      throw new Error("config set --type must be one of auto|string|number|boolean|json")
-    }
-    const devVarsPath = typeof flags["dev-vars"] === "string"
-      ? path.resolve(process.cwd(), flags["dev-vars"])
-      : path.resolve(process.cwd(), ".dev.vars")
-
-    const baseConfig = readDevVarsConfigJson(devVarsPath) || JSON.parse(JSON.stringify(PROJECT_CONFIG))
-    if (!hasPath(PROJECT_CONFIG, key)) {
-      throw new Error(`Unknown config key: ${key}`)
-    }
-    const value = parseConfigValue(rawValue, type)
-    setPath(baseConfig, key, value)
-    writeDevVarsConfigJson(devVarsPath, baseConfig)
-    print({ ok: true, key, value, devVarsPath })
-    return
-  }
-
   if (command === "model" && subcommand === "set") {
     const model = flags.model
     if (typeof model !== "string" || model.length === 0) {
@@ -710,116 +426,11 @@ const main = async () => {
     return
   }
 
-  if (command === "tools") {
-    const config = loadConfig()
-    const response = await fetch(`${config.serviceUrl}/tools/catalog`)
-    const data = await response.json()
-    if (!response.ok) throw new Error(JSON.stringify(data))
-    print(data)
-    return
-  }
-
-  if (LOCAL_PRIMITIVE_COMMANDS.includes(command) || (command === "document" && isLegacyDocumentSubcommand(subcommand))) {
+  if (LOCAL_PRIMITIVE_COMMANDS.includes(command)) {
     await runLocalPrimitiveCommand(command, subcommand, rest, flags)
     return
   }
 
-  if (command === "call") {
-    const config = loadConfig()
-    const profileName = getProfileName(config, flags.profile)
-    const profile = getProfile(config, profileName)
-    const tool = flags.tool
-    if (typeof tool !== "string") throw new Error("call requires --tool")
-    const args = typeof flags.args === "string" ? JSON.parse(flags.args) : {}
-    const autoUpload = flags["auto-upload"] === true
-    const prepared = await prepareArgsWithLocalUploads(config.serviceUrl, tool, args, {
-      autoUpload,
-    })
-    if (prepared.uploads.length > 0) {
-      process.stderr.write(`[echo-pdf] auto-uploaded local files:\n`)
-      for (const item of prepared.uploads) {
-        process.stderr.write(`  - ${item.localPath} -> ${item.fileId} (${item.tool})\n`)
-      }
-    }
-    const preparedArgs = prepared.args
-    const provider = resolveProviderAlias(profile, flags.provider)
-    const model = typeof flags.model === "string" ? flags.model : resolveDefaultModel(profile, provider)
-    const providerApiKeys = buildProviderApiKeys(config, profileName)
-    const payload = buildToolCallRequest({ tool, args: preparedArgs, provider, model, providerApiKeys })
-    const data = await postJson(`${config.serviceUrl}/tools/call`, payload)
-    print(data)
-    return
-  }
-
-  if (command === "file") {
-    const action = rest[0] || ""
-    const config = loadConfig()
-    if (action === "upload") {
-      const filePath = rest[1]
-      if (!filePath) throw new Error("file upload requires a path")
-      const data = await uploadFile(config.serviceUrl, filePath)
-      print({
-        fileId: data?.file?.id || "",
-        filename: data?.file?.filename || path.basename(filePath),
-        sizeBytes: data?.file?.sizeBytes || 0,
-        file: data?.file || null,
-      })
-      return
-    }
-    if (action === "get") {
-      const fileId = typeof flags["file-id"] === "string" ? flags["file-id"] : ""
-      const out = typeof flags.out === "string" ? flags.out : ""
-      if (!fileId || !out) throw new Error("file get requires --file-id and --out")
-      const savedTo = await downloadFile(config.serviceUrl, fileId, out)
-      print({ ok: true, fileId, savedTo })
-      return
-    }
-    throw new Error("file command supports: upload|get")
-  }
-
-  if (command === "mcp" && subcommand === "initialize") {
-    const config = loadConfig()
-    const data = await postJson(`${config.serviceUrl}/mcp`, buildMcpRequest(1, "initialize"), buildMcpHeaders())
-    print(data)
-    return
-  }
-
-  if (command === "mcp" && subcommand === "tools") {
-    const config = loadConfig()
-    const data = await postJson(`${config.serviceUrl}/mcp`, buildMcpRequest(2, "tools/list"), buildMcpHeaders())
-    print(data)
-    return
-  }
-
-  if (command === "mcp" && subcommand === "call") {
-    const config = loadConfig()
-    const tool = flags.tool
-    if (typeof tool !== "string") throw new Error("mcp call requires --tool")
-    const args = typeof flags.args === "string" ? JSON.parse(flags.args) : {}
-    const data = await postJson(
-      `${config.serviceUrl}/mcp`,
-      buildMcpRequest(3, "tools/call", { name: tool, arguments: args }),
-      buildMcpHeaders()
-    )
-    print(data)
-    return
-  }
-
-  if (command === "mcp" && subcommand === "stdio") {
-    await runMcpStdioCommand(typeof flags["service-url"] === "string" ? flags["service-url"] : undefined)
-    return
-  }
-
-  if (command === "setup" && subcommand === "add") {
-    const tool = rest[0]
-    if (!tool) throw new Error("setup add requires tool name")
-    const config = loadConfig()
-    const mode = typeof flags.mode === "string" ? flags.mode : "http"
-    if (!["http", "stdio"].includes(mode)) throw new Error("setup add --mode must be http|stdio")
-    print(setupSnippet(tool, config.serviceUrl, mode))
-    return
-  }
-
   usage()
   process.exitCode = 1
 }