186 lines
7.4 KiB
Markdown
186 lines
7.4 KiB
Markdown
# OpenCode Toolkit
|
|
|
|
A small, OpenCode V2-native package containing a curated set of engineering
|
|
workflows adapted from ECC, plus a read-only project-status tool and a
|
|
conservative project installer.
|
|
|
|
This is a pre-release (`0.1.0-rc.1`) targeting OpenCode **2.0.24** and Node.js
|
|
**20 or newer**. It is not published to npm; install the package tarball attached
|
|
to the repository release.
|
|
|
|
## Included
|
|
|
|
- Skills: coding standards, security review, and test-driven development.
|
|
- Subagents: planner, code reviewer, and security reviewer.
|
|
- Plugin tool: `toolkit_project_status`, implemented against OpenCode's V2 VCS
|
|
API and exposed in the `toolkit` Code Mode namespace.
|
|
- Optional memory tools, disabled by default. Session memory is isolated by
|
|
project and session; shared project memory requires a separate opt-in.
|
|
- Project installer with JSONC-preserving plugin registration, file ownership
|
|
hashes, collision checks, and protection for locally modified files.
|
|
|
|
Provider/model selection remains the user's OpenCode configuration. The package
|
|
does not enable hooks through a global install or configure credentials.
|
|
|
|
## Optional memory
|
|
|
|
Memory is off unless enabled in the consuming project's plugin options. To turn
|
|
on session memory, convert the installer-added plugin string into an object
|
|
entry, keeping its existing local package path:
|
|
|
|
```jsonc
|
|
{
|
|
"plugins": [
|
|
{
|
|
"package": "./node_modules/@sargatxet/opencode-toolkit",
|
|
"options": {
|
|
"memory": {
|
|
"enabled": true,
|
|
"retentionDays": 30
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
If the project uses `.opencode/opencode.json`, retain the different relative
|
|
path the installer registered (typically `../node_modules/...`). The toolkit
|
|
does not automatically capture prompts, tool results, or session summaries.
|
|
Use `toolkit_memory_save`, `toolkit_memory_list`, `toolkit_memory_get`, and
|
|
`toolkit_memory_delete` explicitly. Retrieval and list previews are returned to
|
|
the current model session as tool output. Memory content is stored through
|
|
OpenCode's plugin storage; do not store credentials or secrets.
|
|
|
|
Session scope is the default and is limited to the current project/session.
|
|
Project-wide sharing remains disabled unless the options also contain
|
|
`"project": true` inside `memory`. Project memories are shared by sessions and
|
|
worktrees belonging to the same canonical OpenCode project. Retention defaults
|
|
to 30 days and can be set from 1 to 3650 days. Expired records are not returned
|
|
and are deleted when accessed; there is no background cleanup job. Delete
|
|
individual records explicitly with `toolkit_memory_delete`.
|
|
|
|
Uninstall preserves a plugin object entry because it may contain user options.
|
|
If you enabled memory by converting the installer-added string to an object,
|
|
remove that plugin entry from the project config yourself when uninstalling.
|
|
|
|
## Install the pre-release
|
|
|
|
From the project where you want to use the toolkit, run:
|
|
|
|
```sh
|
|
npm install --save-dev "https://git.sargatxet.cloud/sargatxet/opencode-toolkit/releases/download/v0.1.0-rc.1/sargatxet-opencode-toolkit-0.1.0-rc.1.tgz"
|
|
npx opencode-toolkit install .
|
|
```
|
|
|
|
This installs the prebuilt package and dependencies directly from the release;
|
|
you do not need to clone the repository or build it. Node.js 20+ and npm must be
|
|
installed. OpenCode itself should be version 2.0.24 for the validated setup.
|
|
|
|
The installer copies the selected skills and agents into `.opencode/`, registers
|
|
the local package directory from `node_modules` in the applicable project
|
|
config, and writes an ownership manifest. This avoids asking OpenCode to fetch
|
|
the package from npm. It does not overwrite
|
|
unmanaged files. If a managed file has been edited since installation, updates
|
|
stop rather than replacing it.
|
|
If both `opencode.json` and `.opencode/opencode.json` exist, installation stops
|
|
until the project consolidates them; this avoids ambiguous V2 config precedence.
|
|
|
|
To remove managed content and the plugin entry when the installer added it:
|
|
|
|
```sh
|
|
npx opencode-toolkit uninstall .
|
|
```
|
|
|
|
Modified managed files are preserved and reported. The installer does not yet
|
|
remove the npm dependency from the consuming project's `package.json`; remove
|
|
that dependency separately if desired.
|
|
|
|
To update, install the newer checkout or tarball into the consuming project,
|
|
then rerun the installer. It updates files that still match their recorded
|
|
hashes and refuses to overwrite a locally modified current file:
|
|
|
|
```sh
|
|
npm install --save-dev /path/to/new-opencode-toolkit.tgz
|
|
npx opencode-toolkit install .
|
|
```
|
|
|
|
## Verify a package tarball
|
|
|
|
For a release candidate, build the package and create a tarball from the checkout:
|
|
|
|
```sh
|
|
npm pack
|
|
```
|
|
|
|
This creates `sargatxet-opencode-toolkit-0.1.0-rc.1.tgz` for the current
|
|
pre-release. In a disposable project, install that tarball
|
|
rather than linking the checkout:
|
|
|
|
```sh
|
|
npm install --save-dev /path/to/sargatxet-opencode-toolkit-0.1.0-rc.1.tgz
|
|
npx opencode-toolkit install .
|
|
npx opencode-toolkit install .
|
|
```
|
|
|
|
The second install should make no content changes. Check that the expected
|
|
`toolkit-*` agents and skills are present under `.opencode/`, and that the
|
|
project config contains the local package plugin path. To verify removal, first
|
|
edit one installed toolkit file, then run:
|
|
|
|
```sh
|
|
npx opencode-toolkit uninstall .
|
|
```
|
|
|
|
The edited file should be reported as preserved; unmodified managed files and
|
|
the toolkit plugin entry should be removed. These install/uninstall checks need
|
|
no model credentials. Plugin activation and tool execution were separately
|
|
smoke-tested with OpenCode 2.0.24 and a local mock OpenAI-compatible endpoint.
|
|
Provider-backed agent delegation and skill behavior remain unverified.
|
|
Memory behavior is covered by deterministic storage-contract tests; persistence
|
|
inside a running OpenCode profile and provider-backed learning flows are not yet
|
|
verified.
|
|
|
|
## Safety boundaries
|
|
|
|
The installer rejects unmanaged-file collisions, symlinked install paths, and
|
|
managed files changed since installation. Its ownership manifest is local
|
|
bookkeeping, not a signed security boundary. Path checks do not protect against
|
|
another process changing the project tree concurrently; use it on a project
|
|
directory whose filesystem is trusted. Uninstall removes files incrementally,
|
|
so resolve any reported I/O error and rerun it rather than deleting the manifest
|
|
manually. See [`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md) for the review
|
|
scope and limitations.
|
|
|
|
After installation, restart or reload OpenCode and select the installed
|
|
`toolkit-*` skills or subagents as needed. The plugin exposes its namespaced
|
|
tool through Code Mode. Configure and authenticate your provider normally in
|
|
OpenCode.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
npm install
|
|
npm run typecheck
|
|
npm test
|
|
npm run test:coverage
|
|
npm pack --dry-run
|
|
```
|
|
|
|
The package is tested against OpenCode `2.0.24` and Node.js `20+`. The unit and
|
|
installer tests are deterministic and do not call an LLM. Plugin activation and
|
|
tool execution were smoke-tested with a local mock OpenAI-compatible endpoint;
|
|
provider-backed agent delegation and skill behavior remain unverified.
|
|
|
|
## Provenance and security
|
|
|
|
- [`docs/PROVENANCE.md`](docs/PROVENANCE.md): ECC source revision, attribution,
|
|
adaptations, and content hashes.
|
|
- [`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md): review scope, result,
|
|
and operational limitations.
|
|
|
|
## License
|
|
|
|
The new implementation is MIT licensed. Adapted ECC material remains subject to
|
|
the preserved MIT notice and attribution described in [`NOTICE.md`](NOTICE.md).
|