Metadata-Version: 2.4
Name: opencode-agent-deploy
Version: 0.2.0
Summary: Install agent tool packages into global or project OpenCode configurations
Project-URL: Homepage, https://pypi.org/project/opencode-agent-deploy/
Author-email: Dark Light <darklight@noreply.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,coding,installer,memory,opencode,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: <3.15,>=3.11
Requires-Dist: platformdirs<5,>=4
Description-Content-Type: text/markdown

# OpenCode Agent Deploy

`opencode-agent-deploy` installs existing agent packages from public PyPI into
isolated Python environments and generates their OpenCode skills, tools, plugins,
and configuration with absolute runtime paths.

Version 0.2.0 supports these already published deploy packages:

- `pdf`: `agent-pdf-workspace==0.1.1`
- `mapper`: `agent-codinglanguage-mapper==1.1.0`
- `memory`: `opencode-markdown-memory==0.1.0`

The upstream packages are not copied or republished. The deploy command downloads
the selected, pinned distributions directly from `https://pypi.org/simple`.

## Requirements

- Python 3.11 through 3.14
- An OpenCode installation
- Network access to public PyPI during deployment

Install the deploy command with an isolated application installer:

```bash
uv tool install opencode-agent-deploy
```

Alternatively, use `pipx install opencode-agent-deploy` or install it into your
own virtual environment.

## Interactive installation

Run:

```bash
opencode-agent-deploy install
```

The command shows all three package names and pinned versions. Select `1`, `2`, `3`,
or a comma-separated combination such as `1,2,3`, then select `global` or `project`
scope and confirm the plan. Global scope writes to the OpenCode config directory.
Project scope writes to `opencode.json` and `.opencode/` below the selected project.

## Automated installation

Install all three packages into the current project:

```bash
opencode-agent-deploy install \
  --package pdf \
  --package mapper \
  --package memory \
  --scope project \
  --target "$PWD" \
  --yes
```

Install only the PDF workspace globally:

```bash
opencode-agent-deploy install \
  --package pdf \
  --scope global \
  --yes
```

Use an explicit global OpenCode config directory when automatic discovery is not
appropriate:

```bash
opencode-agent-deploy install \
  --package mapper \
  --scope global \
  --config-dir "$HOME/.config/opencode" \
  --yes
```

Install only Markdown memory globally:

```bash
opencode-agent-deploy install \
  --package memory \
  --scope global \
  --yes
```

For automation, every selected package is supplied with a repeated `--package`
flag and the scope is supplied with `--scope`. `--json` emits a machine-readable
result. `--dry-run` downloads and validates the packages in temporary environments
and performs collision checks without writing OpenCode files or managed environments.

## Managed files and environments

Each deploy package gets a separate virtual environment under the platform data
directory for `opencode-agent-deploy`. Global environments use
`venvs/global/<package>`. Project environments use
`venvs/projects/<project-hash>/<package>`, so project dependencies cannot collide.

Generated OpenCode artifacts contain the absolute Python or console-script path
from their managed environment. The PDF skill and TypeScript tool therefore call
the selected `pdfws` executable directly. The mapper skill, plugin, and agent
configuration use the selected mapper environment's Python interpreter directly.
The Markdown memory TypeScript tool calls its managed
`opencode-markdown-memory` executable directly. No shell activation or ambient
`PATH` modification is required.

Markdown memory configuration and data are scope-local. Global deployment uses
`<opencode-config>/opencode-markdown-memory/`; project deployment uses
`<project>/.opencode/opencode-markdown-memory/`. The generated `config.toml` is
deploy-owned. The mutable `MEMORY.md` is initialized atomically on first use and is
never placed under deploy ownership, so later deployments cannot overwrite memories.

The installer owns only files recorded in
`opencode-agent-deploy-manifest.json`. It preserves unrelated OpenCode configuration
and refuses to overwrite:

- an existing destination it does not own;
- an owned destination changed locally since the previous deployment;
- a symlink in a managed path;
- malformed or unexpected exporter output.

Artifact updates and the ownership manifest are committed atomically. Existing
package environments are restored if preparation or validation fails.

## OpenCode verification

Restart OpenCode after a successful deployment so it reloads project or global
integrations. Confirm that the installed PDF skills/tools, mapper skill/plugin/agent,
and five `markdown_memory_*` CRUD tools appear in the intended scope. The command
output identifies the config file, manifest, environments, and generated artifacts;
`--json` is useful for scripted verification.

## Trust boundary

Deployment installs and executes the pinned upstream exporters. Only use releases
you trust. Subprocesses are invoked as argument arrays without a shell, and package
downloads are restricted to the public PyPI simple index. The deploy command does
not read or print credential files and does not manage PyPI credentials.

Security reporting and supported-version policy are in [SECURITY.md](SECURITY.md).
The reproducible maintainer procedure is in [docs/release.md](docs/release.md).
