# Install

> Sync source: `docs/INSTALL.md`, `docs/TESTING.md`, `package.json`

## Requirements

- **opencode 2** with the V2 plugin API. This release pins `@opencode-ai/plugin@0.0.0-next-17444` (exact). The V2 API is beta — the plugin loads only in opencode 2 builds that ship a compatible plugin package. It does not load in opencode V1.
- **pandoc** — required for DOCX/XLSX/PPTX/PDF write. `brew install pandoc` (macOS) or `sudo apt-get install pandoc` (Linux).
- **PDF write engine** — `xelatex` (default) or `typst`. See [Configuration](Configuration.md).
- **Bun** — local development only.

PDF read (pdfjs-dist + pdf-inspector) and image OCR (anydoc) are built in; no extra install.

## Add the package (recommended)

Add to the `plugins` array in `opencode.json` — project root, or `~/.config/opencode/opencode.json` for all projects:

```json
{ "plugins": ["@xirothedev/openoffice-plugin-opencode"] }
```

opencode installs the package and its dependencies on startup.

### Pin a version and pass options

```json
{
  "plugins": [
    {
      "package": "@xirothedev/openoffice-plugin-opencode@0.2.1",
      "options": { "pdfEngine": "typst", "staleLockHours": 48, "dataDir": "/shared/office-plugin-data" }
    }
  ]
}
```

## Verify it loaded

```bash
opencode2 api get /api/plugin   # "openoffice" should be in the list
```

Then ask opencode: "Create a Word document at /tmp/test.docx with a table". The agent should call `officecli(action="create", ...)`, then `officecli(action="accept", ...)`.

If the tool is missing, check the server log `~/.local/share/opencode/log/opencode.log` for plugin load errors.

## Local development

```bash
bun install
bun run build          # tsc + tsc-alias
bun link --global
cd ~/.config/opencode && bun link @xirothedev/openoffice-plugin-opencode --global
opencode2
```

Check commands: `bun run check` (lint + typecheck + test + build), `bun test`, `bun run test:coverage`.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Plugin not loading | Confirm the file is `opencode.json` (project or global) and the field is `plugins` (V2, not V1's `plugin`). Check package name spelling. Check server log for load errors. |
| `officecli` not available in chat | Restart opencode 2 after a config change. Check startup logs. |
| Tools invisible to the model | Tools register with `codemode: false` for direct provider exposure. Confirm the opencode build matches the pinned `@opencode-ai/plugin`. |
| pandoc errors on Office/PDF write | Install pandoc; verify with `pandoc --version`. |
| Permission errors | The plugin needs write access to its data dir (default `~/.local/share/opencode/plugins/openoffice/`, or configured `dataDir`). |

## Maintainer notes

- Releases publish via CI OIDC trusted publishing (Node 24); `prepublishOnly` runs the build.
- Manual tool invocation (without opencode): decode input through `officecliTool.input`, run `execute` with `Effect.runPromise`. See `docs/TESTING.md`.