@xberg-io/opencode-xberg 0.1.0

package/.opencode/plugins/xberg.js

@@ -0,0 +1,132 @@
+import { spawn } from "node:child_process";
+import { tool } from "@opencode-ai/plugin";
+
+const schema = tool.schema;
+
+const wireFormat = schema
+  .enum(["text", "json", "toon"])
+  .default("json")
+  .describe("CLI output format.");
+
+const contentFormat = schema
+  .enum(["plain", "markdown", "djot", "html", "json"])
+  .optional()
+  .describe("Document content rendering format.");
+
+function hasValue(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function pushOption(args, name, value) {
+  if (hasValue(value)) {
+    args.push(name, String(value));
+  }
+}
+
+function validateJson(value, name) {
+  if (!hasValue(value)) {
+    return;
+  }
+
+  try {
+    JSON.parse(value);
+  } catch (error) {
+    throw new Error(`${name} must be valid JSON: ${error.message}`);
+  }
+}
+
+function runCli(args, context) {
+  const directory = context?.directory ?? context?.worktree ?? process.cwd();
+
+  return new Promise((resolve, reject) => {
+    const child = spawn("xberg", args, {
+      cwd: directory,
+      env: process.env,
+      signal: context?.abort,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    const stdout = [];
+    const stderr = [];
+
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on("error", (error) => {
+      if (error.code === "ENOENT") {
+        resolve({
+          title: "xberg CLI not found",
+          output:
+            "Install the xberg CLI with `brew install xberg-io/tap/xberg`, or run it via `npx xberg` / `uvx --from xberg xberg`.",
+          metadata: { exitCode: 127, command: "xberg", subcommand: args[0] },
+        });
+        return;
+      }
+      reject(error);
+    });
+    child.on("close", (exitCode, signal) => {
+      const stdoutText = Buffer.concat(stdout).toString("utf8").trim();
+      const stderrText = Buffer.concat(stderr).toString("utf8").trim();
+      const output = [stdoutText, stderrText && `stderr:\n${stderrText}`]
+        .filter(Boolean)
+        .join("\n\n");
+
+      resolve({
+        title: exitCode === 0 ? `xberg ${args[0]}` : `xberg ${args[0]} failed`,
+        output: output || "(no output)",
+        metadata: {
+          exitCode,
+          signal,
+          command: "xberg",
+          subcommand: args[0],
+        },
+      });
+    });
+  });
+}
+
+export const XbergPlugin = async () => ({
+  tool: {
+    xberg_extract: tool({
+      description:
+        "Extract text, tables, metadata, and images from a local document with the xberg CLI.",
+      args: {
+        path: schema.string().min(1).describe("Path to the local document."),
+        format: wireFormat,
+        content_format: contentFormat,
+        mime_type: schema.string().min(1).optional().describe("Optional MIME type hint."),
+        config_json: schema.string().min(2).optional().describe("Optional ExtractionConfig JSON."),
+      },
+      async execute(args, context) {
+        validateJson(args.config_json, "config_json");
+
+        const cliArgs = ["extract", args.path, "--format", args.format];
+        pushOption(cliArgs, "--content-format", args.content_format);
+        pushOption(cliArgs, "--mime-type", args.mime_type);
+        pushOption(cliArgs, "--config-json", args.config_json);
+
+        return runCli(cliArgs, context);
+      },
+    }),
+    xberg_detect: tool({
+      description: "Detect the MIME type for a local file with the xberg CLI.",
+      args: {
+        path: schema.string().min(1).describe("Path to the local file."),
+        format: wireFormat,
+      },
+      async execute(args, context) {
+        return runCli(["detect", args.path, "--format", args.format], context);
+      },
+    }),
+    xberg_formats: tool({
+      description: "List document formats supported by the xberg CLI.",
+      args: {
+        format: wireFormat,
+      },
+      async execute(args, context) {
+        return runCli(["formats", "--format", args.format], context);
+      },
+    }),
+  },
+});
+
+export default XbergPlugin;

package/README.md

@@ -0,0 +1,129 @@
+# xberg
+
+Extract text, tables, metadata, and images from 91+ document formats — PDF, Office, images with OCR, HTML, email, archives, academic — using the local `xberg` CLI in your agent.
+
+<!-- TODO: screenshot -->
+
+## Install
+
+### From the marketplace (recommended)
+
+Pending review for official Claude marketplace.
+
+Self-host:
+
+```text
+/plugin marketplace add xberg-io/plugins
+/plugin install xberg@xberg
+```
+
+### Binary requirement
+
+Install the `xberg` CLI:
+
+```bash
+brew install xberg-io/tap/xberg
+```
+
+Or run without a persistent install:
+
+```bash
+npx @xberg-io/xberg-cli --help
+uvx --from xberg-cli xberg --help
+```
+
+Or download a prebuilt binary from the [latest GitHub release](https://github.com/xberg-io/xberg/releases/latest), or install the CLI from crates.io:
+
+```bash
+cargo install xberg-cli --features mcp
+```
+
+The Python (`xberg`) and Node (`@xberg-io/xberg`) packages are language SDKs/bindings, not the CLI. The prebuilt CLI binaries (brew, GitHub release) include the MCP server; a source build enables it with `--features mcp` (`mcp` is not in the CLI's default feature set).
+
+OCR ships with Tesseract by default. Install language packs for non-English documents:
+
+```bash
+brew install tesseract-lang        # macOS
+sudo apt install tesseract-ocr-*   # Debian/Ubuntu
+```
+
+## Skills shipped
+
+| Skill | Trigger |
+|-------|---------|
+| **xberg** | Extract text, tables, metadata, and images from 91+ document formats (PDF, Office, images, HTML, email, archives, academic) using Xberg. Use when writing code that calls Xberg APIs in Python, Node.js/TypeScript, Rust, or CLI. Covers installation, extraction (sync/async), configuration (OCR, chunking, output format), batch processing, error handling, and plugins. |
+| **extracting-with-ocr** | Use when extracting text from scanned PDFs, photographed pages, or images that have no embedded text layer. Covers OCR backends, language packs, force-OCR, and performance tuning. |
+| **extracting-tables** | Use when extracting tabular data from PDFs, spreadsheets, or images. Covers layout-aware table detection, table model selection, output formats (markdown / JSON cells), and known limits. |
+| **chunking** | Use when splitting extracted text into chunks for LLM context windows or RAG ingestion. Covers chunk size, overlap, markdown/yaml/semantic chunkers, tokenizer-based sizing, and the standalone `chunk` command. |
+| **extracting-keywords** | Use when extracting keywords (YAKE/RAKE), detecting document language, or generating embeddings for RAG and search. Covers the keyword config, `--detect-language`, and the standalone `embed` command. |
+| **batch-extraction** | Use when extracting from many files at once with shared config, bounded parallelism, per-file overrides, and error recovery. Covers the `batch` command, `--file-configs`, `--max-concurrent`, and output layout. |
+| **picking-a-format** | Use when choosing an output format for extracted documents — text, markdown, djot, html, or JSON. Maps consumer (LLM, parser, archive) to the right `--format` / `--content-format` pair. |
+
+**Reference materials** (linked from the `xberg` skill):
+
+| Reference | Content |
+|-----------|---------|
+| **CLI Reference** | All commands, flags, config precedence, exit codes |
+| **Configuration Reference** | TOML/YAML/JSON formats, auto-discovery, env vars, full schema |
+| **Supported Formats** | All 91+ formats with file extensions and MIME types |
+| **Python API Reference** | All functions, config classes, plugin protocols, exact signatures |
+| **Node.js API Reference** | All functions, TypeScript interfaces, worker pool APIs |
+| **Rust API Reference** | All functions with feature gates, structs, Cargo.toml examples |
+| **Advanced Features** | Plugins, embeddings, MCP server, API server, security limits |
+| **Other Language Bindings** | Go, Ruby, Java, C#, PHP, Elixir, WASM, Docker |
+
+## MCP tools
+
+Run `xberg mcp` to start the MCP server over stdio. The server exposes 9 tools:
+
+**Extraction:** `extract`, `extract_batch`, `detect_mime_type`
+
+**Cache:** `cache_stats`, `cache_clear`, `cache_manifest`, `cache_warm`
+
+**Metadata:** `list_formats`, `get_version`
+
+The `extract` and `extract_batch` tools accept an optional `config` object to override defaults and a `response_format` of `json` (default) or `toon`. There is no separate `extract_bytes` tool — `extract`/`extract_batch` take an `input` object whose `kind` is `bytes` or `uri`. The MCP server is gated behind the CLI's `mcp` build feature.
+
+## Configuration
+
+Xberg auto-discovers `xberg.toml` from the current directory upward. Set config via:
+
+1. **Environment variable**: `XBERG_CONFIG_JSON='{"output_format":"markdown"}'`
+2. **Config file** (TOML): `xberg.toml` in cwd or a parent directory.
+3. **CLI flag**: `xberg extract doc.pdf --content-format markdown`
+
+See `skills/xberg/references/configuration.md` for the full schema and precedence rules.
+
+## Examples
+
+Extract a PDF to plain text and print it:
+
+```text
+xberg extract document.pdf
+```
+
+Extract with markdown formatting for LLM context:
+
+```text
+xberg extract report.pdf --content-format markdown
+```
+
+Extract tables from a spreadsheet as JSON:
+
+```text
+xberg extract data.xlsx --format json
+```
+
+## Versioning
+
+The plugin version tracks the marketplace `VERSION` file. See [CHANGELOG.md](../../CHANGELOG.md) for release notes.
+
+## License
+
+MIT. The skill content uses Elastic-2.0 references to the upstream [xberg](https://github.com/xberg-io/xberg) repository.
+
+## See also
+
+- **Marketplace**: [xberg-io/plugins](https://github.com/xberg-io/plugins)
+- **Upstream**: [xberg-io/xberg](https://github.com/xberg-io/xberg)
+- **Sibling plugins**: [crawlberg](../crawlberg/README.md)

package/assets/icon.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" width="256" height="256">
+  <rect width="256" height="256" rx="48" fill="#1F6FEB"/>
+  <path d="M64 64 L152 64 L192 104 L192 200 C192 204.4 188.4 208 184 208 L64 208 C59.6 208 56 204.4 56 200 L56 72 C56 67.6 59.6 64 64 64 Z" fill="white"/>
+  <path d="M152 64 L152 96 C152 100.4 155.6 104 160 104 L192 104 Z" fill="#1F6FEB"/>
+  <rect x="80" y="128" width="88" height="12" rx="6" fill="#1F6FEB"/>
+  <rect x="80" y="152" width="96" height="12" rx="6" fill="#1F6FEB"/>
+  <rect x="80" y="176" width="64" height="12" rx="6" fill="#1F6FEB"/>
+</svg>

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@xberg-io/opencode-xberg",
+  "version": "0.1.0",
+  "description": "OpenCode tools for local document extraction with the xberg CLI.",
+  "keywords": [
+    "document-intelligence",
+    "extraction",
+    "ocr",
+    "opencode",
+    "pdf"
+  ],
+  "homepage": "https://github.com/xberg-io/plugins/tree/main/plugins/xberg",
+  "bugs": {
+    "url": "https://github.com/xberg-io/plugins/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xberg-io/plugins.git",
+    "directory": "plugins/xberg"
+  },
+  "files": [
+    ".opencode/",
+    "assets/",
+    "README.md"
+  ],
+  "type": "module",
+  "main": ".opencode/plugins/xberg.js",
+  "exports": {
+    ".": "./.opencode/plugins/xberg.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.17.8"
+  },
+  "engines": {
+    "node": ">=22.14.0"
+  }
+}