From 6629e6ffca5ea6042b4493c3d23f86fbbede34ce Mon Sep 17 00:00:00 2001 From: Toni Ramiro Date: Thu, 8 Oct 2026 13:55:06 +0200 Subject: [PATCH] docs(release): prepare documented release candidate --- CHANGELOG.md | 4 +++ README.md | 71 +++++++++++++++++++++++++++++++------ TODO.md | 4 +++ docs/IMPLEMENTATION-PLAN.md | 11 +++++- docs/SECURITY-REVIEW.md | 44 +++++++++++++++++++++++ package.json | 4 ++- 6 files changed, 125 insertions(+), 13 deletions(-) create mode 100644 docs/SECURITY-REVIEW.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 4053774..db299d1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ All notable changes to this project are documented here. ## [Unreleased] +### Documentation +- Document release-candidate tarball verification and record the pre-release + installer security review and its operational limitations. + ### Fixed - Register the project-local plugin directory instead of prompting OpenCode to download the unpublished package from npm; enable the namespaced tool through diff --git a/README.md b/README.md index 9fcad98..e3d53eb 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,59 @@ 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 @@ -65,21 +118,17 @@ npm run test:coverage npm pack --dry-run ``` -The package is tested against OpenCode `2.0.24`. 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 and skill workflows are not yet complete. See [`FIXME.md`](FIXME.md) and -[`TODO.md`](TODO.md). +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. -## Project documentation +## Provenance and security -- [`AGENTS.md`](AGENTS.md): verified development commands and conventions. -- [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md): accepted plan, - phases, scope, and acceptance criteria. - [`docs/PROVENANCE.md`](docs/PROVENANCE.md): ECC source revision, attribution, adaptations, and content hashes. -- [`CHANGELOG.md`](CHANGELOG.md): user-visible changes. -- [`TODO.md`](TODO.md) and [`FIXME.md`](FIXME.md): remaining work and known gaps. +- [`docs/SECURITY-REVIEW.md`](docs/SECURITY-REVIEW.md): review scope, result, + and operational limitations. ## License diff --git a/TODO.md b/TODO.md index 069477c..d54ca96 100644 --- a/TODO.md +++ b/TODO.md @@ -21,6 +21,10 @@ array merge and precedence behavior. - [x] Install the package tarball into a clean project outside this repository; verify CLI idempotency and native agent discovery. +- [x] Document how to install and verify a release-candidate tarball without + credentials, including idempotency and conservative uninstall checks. +- [x] Perform and record a pre-release manual security review of installer paths, + file ownership, configuration edits, and failure limitations. - [ ] Add provider-backed verification after confirming credentials and model usage budget with the user. - [ ] Confirm repository/package names and decide whether to publish. diff --git a/docs/IMPLEMENTATION-PLAN.md b/docs/IMPLEMENTATION-PLAN.md index 0a33316..f567372 100644 --- a/docs/IMPLEMENTATION-PLAN.md +++ b/docs/IMPLEMENTATION-PLAN.md @@ -139,13 +139,22 @@ provider-backed agent delegation and skill behavior remain unverified. runtime; config collisions are handled or reported before writes; the V2 plugin and its custom tool are confirmed active. -### Phase 5 — Document and release (documentation baseline complete) +### Phase 5 — Document and release (release candidate prepared; publication pending) - Document scope, installation, update/uninstall, compatibility, provenance, and known limitations. - Run deterministic checks and security review before release. - Confirm package/repository names and get explicit approval before publishing. +**Progress:** README now documents checkout installation, tarball verification, +update/uninstall behavior, compatibility, and credential-free checks. A manual +pre-release review of installer paths, ownership, JSONC edits, symlinks, and +failure behavior found no release blocker for trusted project-local use; its +filesystem and provider-backed limitations are recorded in +[`SECURITY-REVIEW.md`](SECURITY-REVIEW.md). Typecheck, all 16 tests, coverage +(87.4% lines), and package dry-run passed. Publication remains blocked on +explicit confirmation of the package/repository identity and destination. + **Acceptance:** another user can install from documented instructions and verify the deterministic behavior without credentials. diff --git a/docs/SECURITY-REVIEW.md b/docs/SECURITY-REVIEW.md new file mode 100644 index 0000000..011959d --- /dev/null +++ b/docs/SECURITY-REVIEW.md @@ -0,0 +1,44 @@ +# Pre-release security review + +## Scope + +Manual source review of the project installer, JSONC configuration edits, CLI, +and packaged content before the first release. The review focused on path +containment, symlink handling, file ownership, preserving user changes, and +partial failures. This is not an independent audit, a guarantee against local +filesystem attackers, or a review of provider/model behavior. + +## Result + +No release-blocking issue was identified for the documented project-local use +on a trusted filesystem. The installer resolves the project root, restricts +manifest paths to toolkit asset locations, rejects symlinked install paths and +non-regular files, refuses unmanaged collisions, and verifies hashes before +replacing or removing managed content. Configuration changes use JSONC edits +and preserve unrelated entries. Deterministic tests cover collisions, modified +files, symlinked install directories, and a tampered manifest. + +## Limitations and operational guidance + +- The installer does not defend against a concurrent process replacing a path + after it has been checked (a filesystem time-of-check/time-of-use race). Run it + only where another actor cannot concurrently manipulate the project tree. +- The ownership manifest is ordinary project-local JSON, not an authenticated + record. It protects against accidental overwrite/removal, not a malicious + project owner who can edit both the manifest and files. +- Uninstall removes managed files incrementally. If an I/O failure interrupts + it, the manifest is retained for recovery in normal mid-operation failures; + resolve the filesystem problem and rerun uninstall. Transactional rollback + for uninstall remains future work. +- Provider-backed agent delegation and skill invocation have not been reviewed + or verified. The runtime smoke test only covered plugin activation and the + read-only status tool with a local mock provider. + +## Checks run + +- `npm run typecheck` — passed. +- `npm test` — passed, 16 tests. +- `npm run test:coverage` — passed; 87.4% lines, 95.23% functions, and 81.86% + branches. +- `npm pack --dry-run` — passed; included runtime files, selected content, + licenses, notice, and README. diff --git a/package.json b/package.json index f198d37..634a778 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,9 @@ "LICENSE", "LICENSE-ECC", "NOTICE.md", - "README.md" + "README.md", + "docs/PROVENANCE.md", + "docs/SECURITY-REVIEW.md" ], "scripts": { "build": "tsc -p tsconfig.json",