Metadata-Version: 2.4
Name: opencode-agent-deploy
Version: 0.4.2
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,folder,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: pip<27,>=23
Requires-Dist: platformdirs<5,>=4
Description-Content-Type: text/markdown

# OpenCode Agent Deploy

`opencode-agent-deploy` installs existing agent packages from public PyPI into the
virtual environment that executes the deploy command. It generates their OpenCode
skills, tools, and plugins with absolute paths back to that same
environment.

Version 0.4.2 supports these already published deploy packages:

- `pdf`: `agent-pdf-workspace==0.1.1`
- `mapper`: `agent-codinglanguage-mapper==1.1.1`
- `memory`: `opencode-markdown-memory==0.1.0`
- `folder`: `agent-folder-workspace==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. Its application
environment becomes the shared default runtime for all selected packages:

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

Alternatively, use `pipx install opencode-agent-deploy` or install it into your
own activated virtual environment. The command rejects the default runtime mode
when it is executed by a system Python outside a virtual environment.

## Interactive installation

Run:

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

The command shows all four package names and pinned versions. Select `1`, `2`, `3`,
`4`, or a comma-separated combination such as `1,2,3,4`, then select `global` or
`project` scope and confirm the plan. Global scope writes generated artifacts to
the OpenCode config directory. Project scope writes them below `.opencode/` in
the selected project. In both scopes, `opencode.json` remains user-owned.

## Automated installation

Install all four packages into the current project:

```bash
opencode-agent-deploy install \
  --package pdf \
  --package mapper \
  --package memory \
  --package folder \
  --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
```

Install only the folder workspace globally:

```bash
opencode-agent-deploy install \
  --package folder \
  --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. The default `--runtime current` installs into the executing venv and cannot
be combined with `--dry-run`. Use `--runtime isolated --dry-run` to download and
validate packages in temporary environments and collision-check OpenCode files
without committing them.

## Runtime selection and managed files

The default `current` runtime installs all selected, exactly pinned packages with
one dependency resolution into `sys.prefix`, the venv that contains and executes
`opencode-agent-deploy`. It does not create another venv. On Windows this means the
packages and commands remain in that environment's `Lib\site-packages` and
`Scripts` directories; no package venv is created below `%LOCALAPPDATA%`.

The previous per-package behavior remains available with `--runtime isolated`.
It creates separate environments below the platform data directory: global
environments use `venvs/global/<package>`, while project environments use
`venvs/projects/<project-hash>/<package>`.

Generated OpenCode artifacts contain the absolute Python or console-script path
from the selected runtime. In the default mode, Python is exactly the interpreter
that executes `opencode-agent-deploy`, and console scripts are taken from the same
venv. The PDF skill and TypeScript tool therefore call
the selected `pdfws` executable directly. The package-named mapper skill, plugin,
and Markdown agent use that Python interpreter directly. The Markdown memory
TypeScript tool calls its
`opencode-markdown-memory` executable directly. No shell activation or ambient
`PATH` modification is required.

The folder workspace skill and project-aware plugin are generated by the upstream
package. The plugin calls the selected Python interpreter directly and starts one
local stdio MCP server for the normalized active OpenCode project root.

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 generated files recorded in
`opencode-agent-deploy-manifest.json`. It never reads, writes, deletes, or claims
ownership of `opencode.json`. Upgrading from an older deploy release removes any
prior manifest claim on that path without inspecting or changing the file.

The mapper is installed as
`skills/agent-codinglanguage-mapper/SKILL.md` and
`agents/agent-codinglanguage-mapper.md` within the selected integration root.
Markdown memory still needs the user to allow its tools in their own OpenCode
configuration, for example:

```json
{
  "permission": {
    "markdown_memory_*": "allow"
  }
}
```

For other generated artifacts, the installer 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. Isolated
package environments are restored if preparation or validation fails. Package
changes inside the default executing venv are ordinary pip changes and are not
rolled back when a later OpenCode artifact step fails.

## OpenCode verification

Restart OpenCode after a successful deployment so it reloads project or global
integrations. Confirm that the installed PDF skills/tools, package-named mapper
skill/plugin/Markdown agent,
five `markdown_memory_*` CRUD tools, and folder workspace skill/plugin/MCP server
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).
