137 lines
5.2 KiB
Markdown
137 lines
5.2 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 an early development release. It currently targets OpenCode **2.0.24**
|
|
and Node.js **20 or newer**. It is not yet published to npm.
|
|
|
|
## 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.
|
|
- 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.
|
|
|
|
## Install from a local checkout
|
|
|
|
Until a release is published, install the package from its checkout in the
|
|
project where it will be used:
|
|
|
|
```sh
|
|
npm install --save-dev /path/to/opencode-toolkit
|
|
npx opencode-toolkit install .
|
|
```
|
|
|
|
Replace `/path/to/opencode-toolkit` with the checkout path on your machine.
|
|
|
|
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 provisional, unpublished package name 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.tgz` for the current provisional
|
|
package identity and version. 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.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.
|
|
|
|
## 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).
|