document-ocr 0.0.0-stage → 3.1.3

package/python/requirements.lock

@@ -0,0 +1,134 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile pyproject.toml -o requirements.lock --python-version 3.14 --universal
+annotated-doc==0.0.5
+    # via fastapi
+annotated-types==0.8.0
+    # via pydantic
+anyio==4.15.1
+    # via
+    #   starlette
+    #   watchfiles
+certifi==2026.7.22
+    # via requests
+cffi==2.1.1 ; platform_python_implementation != 'PyPy'
+    # via cryptography
+charset-normalizer==3.5.2
+    # via requests
+click==8.5.0
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   uvicorn
+colorama==0.4.6 ; sys_platform == 'win32'
+    # via
+    #   colorlog
+    #   tqdm
+colorlog==6.12.0
+    # via rapidocr
+cryptography==50.0.2
+    # via india-document-ocr (pyproject.toml)
+fastapi==0.143.0
+    # via india-document-ocr (pyproject.toml)
+flatbuffers==25.12.19
+    # via onnxruntime
+h11==0.16.0
+    # via uvicorn
+httptools==0.9.0
+    # via uvicorn
+idna==3.20
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   anyio
+    #   requests
+numpy==2.5.4
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   onnxruntime
+    #   opencv-python
+    #   rapidocr
+    #   shapely
+omegaconf==2.4.0
+    # via rapidocr
+onnxruntime==1.31.0
+    # via india-document-ocr (pyproject.toml)
+opencv-python==4.13.0.92
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   rapidocr
+opentelemetry-api==1.45.1
+    # via fastapi
+packaging==26.3
+    # via onnxruntime
+pillow==12.3.0
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   pillow-heif
+    #   rapidocr
+pillow-heif==1.8.1
+    # via india-document-ocr (pyproject.toml)
+protobuf==7.36.2
+    # via onnxruntime
+pyclipper==1.4.0
+    # via rapidocr
+pycountry==26.2.16
+    # via india-document-ocr (pyproject.toml)
+pycparser==3.11 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy'
+    # via cffi
+pydantic==2.14.1
+    # via fastapi
+pydantic-core==2.50.1
+    # via pydantic
+pypdfium2==5.14.0
+    # via india-document-ocr (pyproject.toml)
+python-dotenv==1.2.4
+    # via uvicorn
+python-multipart==0.0.32
+    # via india-document-ocr (pyproject.toml)
+pyyaml==6.0.3
+    # via
+    #   omegaconf
+    #   rapidocr
+    #   uvicorn
+rapidfuzz==3.14.6
+    # via india-document-ocr (pyproject.toml)
+rapidocr==3.9.2
+    # via india-document-ocr (pyproject.toml)
+requests==2.34.2
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   rapidocr
+shapely==2.2.0
+    # via rapidocr
+six==1.17.0
+    # via rapidocr
+starlette==1.7.0
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   fastapi
+tqdm==4.70.1
+    # via rapidocr
+typing-extensions==4.16.0
+    # via
+    #   anyio
+    #   fastapi
+    #   opentelemetry-api
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.4
+    # via
+    #   fastapi
+    #   pydantic
+urllib3==2.8.0
+    # via
+    #   india-document-ocr (pyproject.toml)
+    #   requests
+uvicorn==0.54.0
+    # via india-document-ocr (pyproject.toml)
+uvloop==0.23.0 ; platform_python_implementation != 'PyPy' and sys_platform != 'cygwin' and sys_platform != 'win32'
+    # via uvicorn
+watchfiles==1.3.0
+    # via uvicorn
+websockets==17.2
+    # via uvicorn
+zxing-cpp==3.1.1
+    # via india-document-ocr (pyproject.toml)

package/python/server.py

@@ -0,0 +1,313 @@
+"""
+FastAPI server wrapping the passport OCR pipeline.
+
+Used by the document-ocr npm package to run OCR locally.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+import logging
+import os
+import secrets
+import uuid
+from functools import partial
+from pathlib import Path
+
+from fastapi import FastAPI, File, Form, Header, UploadFile, HTTPException
+from fastapi.responses import JSONResponse, HTMLResponse, Response
+
+from core.kyc_ocr import KycOCRConfigError
+from core.ocr_engine import OCRModelInitError
+from core.pipeline import scan
+from core.document_bundle import scan_batch, scan_document
+from core.document_registry import list_document_profiles, validate_document_hint
+from core.barcodes import barcode_decoder_available
+from core.jobs import configured_store
+from core.redaction import redact, render_preview
+from core.preprocessor import ImageQualityError
+
+# ---------------------------------------------------------------------------
+# Config
+# ---------------------------------------------------------------------------
+
+MAX_UPLOAD_SIZE = 10 * 1024 * 1024  # 10 MB
+SCAN_TIMEOUT_SECONDS = 60.0
+logger = logging.getLogger("document-ocr")
+# uvicorn configures only its own loggers, so without a handler these per-scan
+# INFO lines (status, page type, confidence, timing; never document text) were
+# dropped. Scoped to this logger so core modules keep their default level.
+if not logger.handlers:
+    _handler = logging.StreamHandler()
+    _handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+    logger.addHandler(_handler)
+    logger.setLevel(logging.INFO)
+    logger.propagate = False
+# Matches the sibling pdf-worker service so a deployment sets one variable name
+# everywhere. Unset means no auth is enforced, which is what local development wants.
+API_TOKEN = os.getenv("API_TOKEN") or None
+
+_ocr_semaphore = asyncio.Semaphore(1)
+_models_ready = False
+_model_init_error: str | None = None
+
+# ---------------------------------------------------------------------------
+# App lifecycle
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def _lifespan(app: FastAPI):
+    global _models_ready, _model_init_error
+    _models_ready = False
+    _model_init_error = None
+    logger.info("Loading OCR models...")
+    loop = asyncio.get_running_loop()
+    try:
+        await loop.run_in_executor(None, _warm_up_ocr)
+    except (OCRModelInitError, KycOCRConfigError) as exc:
+        # Stay up so /ready and /scan can report a clear error instead of the
+        # process crash-looping. Liveness (/health) remains green.
+        _model_init_error = str(exc)
+        logger.error("OCR model initialisation failed: %s", exc)
+    else:
+        _models_ready = True
+        logger.info("OCR models loaded.")
+    yield
+
+
+app = FastAPI(title="Document OCR", version="3.1.2", lifespan=_lifespan)
+
+
+@app.middleware("http")
+async def _private_responses(request, call_next):
+    response = await call_next(request)
+    response.headers["Cache-Control"] = "no-store"
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    return response
+
+
+def _warm_up_ocr():
+    from core.kyc_ocr import configured_kyc_languages
+    from core.ocr_engine import _get_ocr
+
+    for language in dict.fromkeys(("en", *configured_kyc_languages())):
+        _get_ocr(language)
+    _get_ocr("en", band=True)  # MRZ band re-reads; avoid loading on a live scan
+
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}
+
+
+@app.get("/ready")
+async def ready():
+    if _model_init_error is not None:
+        return JSONResponse(
+            status_code=503,
+            content={"status": "model_init_failed", "error": _model_init_error},
+        )
+    if not _models_ready:
+        return JSONResponse(status_code=503, content={"status": "loading"})
+    return {"status": "ready"}
+
+
+def _scan_finished(future: asyncio.Future) -> None:
+    _ocr_semaphore.release()
+    # Consume late exceptions after a disconnected/timed-out caller has gone.
+    if not future.cancelled():
+        future.exception()
+
+
+def _authorize(authorization):
+    if API_TOKEN is not None:
+        expected = f"Bearer {API_TOKEN}"
+        if authorization is None or not secrets.compare_digest(authorization, expected):
+            raise HTTPException(status_code=401, detail="UNAUTHORIZED", headers={"WWW-Authenticate": "Bearer"})
+
+
+async def _upload(image: UploadFile) -> bytes:
+    content_type = image.content_type or ""
+    if not content_type.startswith("image/") and content_type != "application/pdf":
+        raise HTTPException(status_code=400, detail="INVALID_CONTENT_TYPE")
+    data = await image.read(MAX_UPLOAD_SIZE + 1)
+    if len(data) > MAX_UPLOAD_SIZE:
+        raise HTTPException(status_code=400, detail="FILE_TOO_LARGE")
+    if not data:
+        raise HTTPException(status_code=400, detail="EMPTY_FILE")
+    return data
+
+
+async def _uploads(images: list[UploadFile]) -> list[bytes]:
+    if not 1 <= len(images) <= 10:
+        raise HTTPException(status_code=400, detail="INVALID_BATCH_SIZE")
+    output, size = [], 0
+    for image in images:
+        data = await _upload(image)
+        size += len(data)
+        if size > MAX_UPLOAD_SIZE:
+            raise HTTPException(status_code=400, detail="BATCH_TOO_LARGE")
+        output.append(data)
+    return output
+
+
+def _options(document_type, country, include_evidence):
+    try:
+        document_type, country = validate_document_hint(document_type, country)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    # Omit defaults for compatibility with one-argument pipeline integrations.
+    return {key: value for key, value in {
+        'document_type': document_type, 'country': country,
+        'include_evidence': include_evidence,
+    }.items() if value}
+
+
+async def _execute(function, *args, **kwargs):
+    request_id = str(uuid.uuid4())[:8]
+    try:
+        deadline = asyncio.get_running_loop().time() + SCAN_TIMEOUT_SECONDS
+        await asyncio.wait_for(_ocr_semaphore.acquire(), timeout=SCAN_TIMEOUT_SECONDS)
+        try:
+            future = asyncio.get_running_loop().run_in_executor(None, partial(function, *args, **kwargs))
+        except BaseException:
+            _ocr_semaphore.release()
+            raise
+        future.add_done_callback(_scan_finished)
+        return await asyncio.wait_for(asyncio.shield(future), timeout=max(0, deadline - asyncio.get_running_loop().time()))
+    except asyncio.TimeoutError:
+        logger.warning("[%s] scan_timeout", request_id)
+        return JSONResponse(status_code=504, content={"error": "SCAN_TIMEOUT"})
+    except OCRModelInitError:
+        logger.error("[%s] model_init_failed", request_id)
+        return JSONResponse(status_code=503, content={"error": "MODEL_INIT_FAILED"})
+    except KycOCRConfigError:
+        logger.error("[%s] invalid_kyc_ocr_config", request_id)
+        return JSONResponse(status_code=503, content={"error": "INVALID_KYC_OCR_CONFIG"})
+    except (ImageQualityError, ValueError) as exc:
+        return JSONResponse(status_code=400, content={"error": str(exc)})
+    except Exception:
+        logger.exception("[%s] internal_error", request_id)
+        return JSONResponse(status_code=500, content={"error": "INTERNAL_ERROR"})
+
+
+@app.post("/scan")
+async def scan_passport(
+    image: UploadFile = File(...), authorization: str | None = Header(default=None),
+    document_type: str | None = Form(default=None), country: str | None = Form(default=None),
+    include_evidence: bool = Form(default=False),
+):
+    _authorize(authorization)
+    options = _options(document_type, country, include_evidence)
+    result = await _execute(scan, await _upload(image), **options)
+    if isinstance(result, Response):
+        return result
+    logger.info("status=%s page_type=%s confidence=%s processing_ms=%s", result.status,
+                result.page_type, result.confidence, result.processing_ms)
+    return JSONResponse(status_code=422 if result.status == 'failure' else 200, content=result.to_dict())
+
+
+@app.get("/documents")
+async def documents(authorization: str | None = Header(default=None)):
+    _authorize(authorization)
+    return {"schemaVersion": 1, "documents": list_document_profiles(),
+            "capabilities": {"barcode": barcode_decoder_available(), "jobs": await asyncio.to_thread(_job_store, required=False) is not None,
+                             "review": True, "multipage": True}}
+
+
+@app.post("/scan/batch")
+async def batch(
+    images: list[UploadFile] = File(...), authorization: str | None = Header(default=None),
+    document_type: str | None = Form(default=None), country: str | None = Form(default=None),
+    include_evidence: bool = Form(default=False),
+):
+    _authorize(authorization)
+    options = _options(document_type, country, include_evidence)
+    return await _execute(scan_batch, await _uploads(images), **options)
+
+
+@app.post("/scan/document")
+async def grouped_document(
+    images: list[UploadFile] = File(...), authorization: str | None = Header(default=None),
+    document_type: str | None = Form(default=None), country: str | None = Form(default=None),
+    include_evidence: bool = Form(default=False),
+):
+    _authorize(authorization)
+    options = _options(document_type, country, include_evidence)
+    return await _execute(scan_document, await _uploads(images), **options)
+
+
+@app.get("/review", response_class=HTMLResponse)
+async def review():
+    import core
+    path = Path(core.__file__).with_name('review.html')
+    return HTMLResponse(path.read_text(), headers={'Cache-Control': 'no-store',
+        'Content-Security-Policy': "default-src 'self'; img-src 'self' blob: data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'"})
+
+
+@app.post("/preview")
+async def preview(image: UploadFile = File(...), authorization: str | None = Header(default=None)):
+    _authorize(authorization)
+    result = await _execute(render_preview, await _upload(image))
+    if isinstance(result, Response):
+        return result
+    return Response(result, media_type='image/png', headers={'Cache-Control': 'no-store'})
+
+
+@app.post("/redact")
+async def redacted(image: UploadFile = File(...), boxes: str = Form(...), authorization: str | None = Header(default=None)):
+    _authorize(authorization)
+    if len(boxes) > 50000:
+        raise HTTPException(status_code=400, detail='INVALID_REDACTION_BOXES')
+    result = await _execute(redact, await _upload(image), boxes)
+    if isinstance(result, Response):
+        return result
+    return Response(result, media_type='image/png', headers={'Cache-Control': 'no-store',
+        'Content-Disposition': 'attachment; filename="redacted.png"'})
+
+
+def _job_store(*, required=True):
+    try:
+        store = configured_store()
+    except ValueError as exc:
+        raise HTTPException(status_code=503, detail='INVALID_JOB_CONFIGURATION') from exc
+    if required and store is None:
+        raise HTTPException(status_code=503, detail='JOBS_NOT_CONFIGURED')
+    return store
+
+
+@app.post('/jobs', status_code=202)
+async def enqueue_job(
+    images: list[UploadFile] = File(...), authorization: str | None = Header(default=None),
+    document_type: str | None = Form(default=None), country: str | None = Form(default=None),
+    include_evidence: bool = Form(default=False), grouped: bool = Form(default=False), notify: bool = Form(default=False),
+):
+    _authorize(authorization)
+    options = _options(document_type, country, include_evidence)
+    store = await asyncio.to_thread(_job_store)
+    data = await _uploads(images)
+    try:
+        return await asyncio.to_thread(store.enqueue, data, options, grouped=grouped, notify=notify)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+
+@app.get('/jobs/{identifier}')
+async def job(identifier: str, authorization: str | None = Header(default=None)):
+    _authorize(authorization)
+    store = await asyncio.to_thread(_job_store)
+    result = await asyncio.to_thread(store.get, identifier)
+    if result is None:
+        raise HTTPException(status_code=404, detail='JOB_NOT_FOUND')
+    return result
+
+
+@app.delete('/jobs/{identifier}')
+async def delete_job(identifier: str, authorization: str | None = Header(default=None)):
+    _authorize(authorization)
+    store = await asyncio.to_thread(_job_store)
+    removed = await asyncio.to_thread(store.delete, identifier)
+    if not removed:
+        raise HTTPException(status_code=404, detail='JOB_NOT_FOUND')
+    return {'deleted': True}

package/scripts/dococr.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const templates = resolve(dirname(fileURLToPath(import.meta.url)), '../hosting')
+const targets = ['cloudrun', 'lambda', 'cloudflare', 'server']
+const usage = `Usage:
+  document-ocr init --target cloudrun|lambda|cloudflare|server [--directory DIR]
+    [--name NAME] [--profile economy|warm] [--languages en,devanagari]
+    [--project PROJECT] [--region REGION] [--image IMAGE_URI] [--domain DOMAIN]
+    [--bucket BUCKET] [--prefix uploads/]
+  document-ocr doctor [--directory DIR] [--endpoint URL] [--json]
+  document-ocr deploy [--directory DIR] [--dry-run]
+
+init writes dococr.json and source/templates; existing files are never replaced.
+Credentials and API_TOKEN come from your environment, never dococr.json.
+Run doctor before deploying; deploy executes the target's bundled wrapper.`
+
+function parse(args) {
+  const [command, ...rest] = args
+  const options = {}
+  const booleans = new Set(['dry-run', 'json', 'help'])
+  const values = new Set(['target', 'directory', 'name', 'profile', 'languages', 'project', 'region', 'image', 'domain', 'bucket', 'prefix', 'endpoint'])
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i]
+    if (!token.startsWith('--')) throw new Error(`Unexpected argument: ${token}`)
+    const key = token.slice(2)
+    if (booleans.has(key)) options[key] = true
+    else if (values.has(key) && rest[i + 1] && !rest[i + 1].startsWith('--')) options[key] = rest[++i]
+    else throw new Error(`Unknown option or missing value: ${token}`)
+  }
+  return { command, options }
+}
+
+function validate(config) {
+  if (!config || config.version !== 1 || !targets.includes(config.target)) throw new Error('Invalid dococr.json: version 1 and a supported target are required')
+  if (!/^[a-z][a-z0-9-]{0,39}$/.test(config.name)) throw new Error('name must start with a lowercase letter and contain at most 40 lowercase letters, digits, or hyphens')
+  if (!['economy', 'warm'].includes(config.profile)) throw new Error('profile must be economy or warm')
+  if (!Array.isArray(config.languages) || config.languages.length < 1 || config.languages.length > 4
+      || config.languages.some((language) => !['en', 'latin', 'devanagari', 'ka', 'ta', 'te'].includes(language))
+      || new Set(config.languages).size !== config.languages.length) throw new Error('languages must list one to four unique supported OCR languages')
+  const allowed = new Set(['version', 'target', 'name', 'profile', 'languages', 'project', 'region', 'image', 'domain', 'bucket', 'prefix', 'endpoint'])
+  for (const key of Object.keys(config)) {
+    if (!allowed.has(key)) throw new Error(`Unknown dococr.json field: ${key}. Keep credentials in environment variables.`)
+    if (['project', 'region', 'image', 'domain', 'bucket', 'prefix', 'endpoint'].includes(key)
+        && (typeof config[key] !== 'string' || !config[key].trim())) throw new Error(`${key} must be a non-empty string`)
+  }
+  return config
+}
+
+function environment(config, env) {
+  const result = { ...env, DOCUMENT_OCR_NAME: config.name, DOCUMENT_OCR_PROFILE: config.profile, DOCUMENT_OCR_KYC_LANGS: config.languages.join(',') }
+  const mapping = { project: 'GCP_PROJECT', image: 'IMAGE_URI', domain: 'DOMAIN', bucket: 'DOCUMENT_OCR_S3_BUCKET', prefix: 'DOCUMENT_OCR_S3_PREFIX' }
+  for (const [key, variable] of Object.entries(mapping)) if (config[key]) result[variable] = config[key]
+  if (config.region) result[config.target === 'lambda' ? 'AWS_REGION' : 'GCP_REGION'] = config.region
+  return result
+}
+
+function invocation(config) {
+  return config.target === 'cloudflare'
+    ? { command: 'npm', args: ['--prefix', 'deploy/cloudflare', 'run', 'deploy'] }
+    : { command: 'bash', args: [`deploy/${config.target}/deploy.sh`] }
+}
+
+function run(command, args, options) {
+  const result = spawnSync(command, args, options)
+  return { status: result.status ?? 1, error: result.error?.message }
+}
+
+/** Injectable command runner keeps CLI tests local and never deploys infrastructure. */
+export async function main(args = process.argv.slice(2), dependencies = {}) {
+  const log = dependencies.log ?? console.log
+  const execute = dependencies.run ?? run
+  const env = dependencies.env ?? process.env
+  const parsed = parse(args)
+  const { command, options } = parsed
+  if (!command || command === '--help' || command === 'help' || options.help) { log(usage); return 0 }
+  if (!['init', 'doctor', 'deploy'].includes(command)) throw new Error(`Unknown command: ${command}`)
+  const acceptedOptions = {
+    init: ['target', 'directory', 'name', 'profile', 'languages', 'project', 'region', 'image', 'domain', 'bucket', 'prefix'],
+    doctor: ['directory', 'endpoint', 'json'],
+    deploy: ['directory', 'dry-run'],
+  }[command]
+  for (const key of Object.keys(options)) {
+    if (!acceptedOptions.includes(key)) throw new Error(`--${key} is not supported by ${command}`)
+  }
+  const cwd = resolve(dependencies.cwd ?? process.cwd(), options.directory ?? '.')
+  const configFile = join(cwd, 'dococr.json')
+
+  if (command === 'init') {
+    const config = validate({
+      version: 1, target: options.target, name: options.name ?? 'document-ocr', profile: options.profile ?? 'economy',
+      languages: (options.languages ?? 'en').split(','),
+      ...Object.fromEntries(['project', 'region', 'image', 'domain', 'bucket', 'prefix'].filter((key) => options[key]).map((key) => [key, options[key]])),
+    })
+    const source = dependencies.templates ?? templates
+    if (!existsSync(join(source, `deploy/${config.target}/deploy.sh`))) throw new Error('Hosting templates are missing; install a built document-ocr package')
+    const entries = readdirSync(source)
+    const collisions = ['dococr.json', ...entries].filter((name) => existsSync(join(cwd, name)))
+    if (collisions.length) throw new Error(`Refusing to overwrite existing paths: ${collisions.join(', ')}`)
+    mkdirSync(cwd, { recursive: true })
+    for (const name of entries) cpSync(join(source, name), join(cwd, name), { recursive: true, errorOnExist: true, force: false })
+    writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx' })
+    log(`Initialized ${config.target} in ${cwd}. Configure credentials, then run document-ocr doctor.`)
+    return 0
+  }
+
+  if (!existsSync(configFile)) throw new Error('dococr.json is missing; run document-ocr init --target TARGET first')
+  const config = validate(JSON.parse(readFileSync(configFile, 'utf8')))
+  const effectiveEnv = environment(config, env)
+  const selected = invocation(config)
+  const wrapper = join(cwd, `deploy/${config.target}/deploy.sh`)
+  if (!existsSync(wrapper)) throw new Error(`Missing deployment wrapper: deploy/${config.target}/deploy.sh`)
+  if (command === 'deploy') {
+    if (options['dry-run']) { log(JSON.stringify({ ...selected, cwd, target: config.target, name: config.name, profile: config.profile }, null, 2)); return 0 }
+    const result = execute(selected.command, selected.args, { cwd, env: effectiveEnv, stdio: 'inherit', shell: false })
+    if (result.error) throw new Error(result.error)
+    return result.status ?? 1
+  }
+
+  const requirements = {
+    cloudrun: ['bash', 'gcloud', 'python3'],
+    lambda: ['bash', 'aws', 'sam', ...(effectiveEnv.IMAGE_URI ? [] : ['docker'])],
+    cloudflare: ['bash', 'node', 'npm', ...(effectiveEnv.IMAGE_URI ? [] : ['docker'])],
+    server: ['bash', 'docker'],
+  }[config.target]
+  const checks = requirements.map((tool) => {
+    const result = execute(tool, ['--version'], { cwd, env: effectiveEnv, stdio: 'pipe', encoding: 'utf8', timeout: 10000, shell: false })
+    return { check: `${tool} installed`, passed: result.status === 0 }
+  })
+  if (config.target === 'server') {
+    const compose = execute('docker', ['compose', 'version'], { cwd, env: effectiveEnv, stdio: 'pipe', timeout: 10000, shell: false })
+    checks.push({ check: 'Docker Compose installed', passed: compose.status === 0 })
+    checks.push({ check: 'DOMAIN configured', passed: Boolean(effectiveEnv.DOMAIN) })
+    checks.push({ check: 'API_TOKEN configured in environment', passed: Boolean(effectiveEnv.API_TOKEN) })
+  }
+  if (config.target === 'cloudrun') checks.push({ check: 'GCP_PROJECT configured', passed: Boolean(effectiveEnv.GCP_PROJECT) })
+  if (!effectiveEnv.IMAGE_URI) checks.push({ check: 'Source and locked runtime bundled', passed: existsSync(join(cwd, 'core/pipeline.py')) && existsSync(join(cwd, 'requirements.lock')) })
+  const endpoint = options.endpoint ?? config.endpoint
+  if (endpoint) {
+    const url = new URL(endpoint)
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('endpoint must be an HTTP(S) URL without credentials')
+    url.pathname = `${url.pathname.replace(/\/+$/, '')}/health`
+    try {
+      const response = await (dependencies.fetch ?? fetch)(url, { signal: AbortSignal.timeout(10000), headers: effectiveEnv.API_TOKEN ? { Authorization: `Bearer ${effectiveEnv.API_TOKEN}` } : {} })
+      const health = await response.json()
+      checks.push({ check: 'Endpoint healthy', passed: response.ok && health.status === 'ok' })
+    } catch { checks.push({ check: 'Endpoint healthy', passed: false }) }
+  }
+  const passed = checks.every((check) => check.passed)
+  if (options.json) log(JSON.stringify({ passed, target: config.target, checks }, null, 2))
+  else for (const check of checks) log(`${check.passed ? 'OK' : 'FAIL'} ${check.check}`)
+  return passed ? 0 : 1
+}
+
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().then((status) => { process.exitCode = status }).catch((error) => {
+    console.error(`document-ocr: ${error.message}`)
+    process.exitCode = 1
+  })
+}