This project publishes to npm from GitHub Actions. It uses --provenance for
Sigstore attestations and a granular npm access token stored in the
NPM_TOKEN GitHub secret for authentication (npm's OIDC trusted-publishing UI
has proven unreliable for this package).
- Create or log in to your npm account: https://www.npmjs.com/
- npm now requires either two-factor authentication (2FA) on your account or a granular access token with "Bypass 2FA" enabled for direct publishing. For the one-time first publish, the bypass-token route below is usually fastest.
Trusted publishing requires the package to already exist on npm. If
opencode-dev-framework has never been published, create a one-time granular
access token and publish manually:
-
On npmjs.com, go to Settings → Access Tokens → Generate New Token → Granular Access Token.
-
Set the token permissions:
- Package:
opencode-dev-framework - Permissions:
Publish - Bypass two-factor authentication: enabled
- Package:
-
Copy the token.
-
Back in your terminal:
npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN" npm publish --access public npm config delete //registry.npmjs.org/:_authToken
This writes the token to your user
~/.npmrc, publishes, and then removes it. Do not commit an.npmrccontaining a token. -
Revoke the token on npmjs.com once the package exists.
After the package exists, configure the GitHub Actions trusted publisher and use OIDC for all future publishes.
- Go to the package page on npmjs.com: https://www.npmjs.com/package/opencode-dev-framework
- Click Settings → Trusted publishing.
- Under Select your publisher, choose GitHub Actions.
- Fill in the form exactly as follows:
- Organization or user:
jwitmann - Repository:
opencode-dev-framework - Workflow filename:
ci.yml - Environment name: leave blank
- Allowed actions: check npm publish
- Organization or user:
- Save the trusted publisher.
⚠️ npm does not validate this form when you save it. Typos only show up asENEEDAUTHwhen the workflow runs, so double-check every field.
The repository.url in package.json must exactly match the GitHub repository
used for trusted publishing:
"repository": {
"type": "git",
"url": "git+https://github.com/jwitmann/opencode-dev-framework.git"
}The repository already contains .github/workflows/ci.yml. The relevant
publish job looks like this:
publish:
name: Publish to npm
if: startsWith(github.ref, 'refs/tags/v')
needs: validate
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
registry-url: https://registry.npmjs.org
- run: npm ci
- run: npm run build
- run: npm publish --provenance --access publicRequirements:
permissions: id-token: writeis mandatory; without it provenance signing fails.registry-url: https://registry.npmjs.orgtellssetup-nodeto configure the registry for publishing.NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}authenticates the publish. Create a granular access token on npmjs.com (see below).--provenanceadds a Sigstore attestation via OIDC; it is independent of the publish token.
Point OpenCode at the local repository root in the project's opencode.json:
{
"plugin": ["/home/jerome/opencode-dev-framework"]
}OpenCode loads dist/index.js, so run npm run build after every source
change. To clear the OpenCode plugin cache and rebuild in one step:
npm run dev:cleanCaveats:
-
opencode plugin <module>writes a.opencode/opencode.json[c]file whose plugin array merges with (never replaces) the project-level config. Delete it or keep its plugin list consistent with the project-level config. -
Clear OpenCode's plugin cache after switching from a published version to a local path:
rm -rf ~/.cache/opencode/packages/opencode-dev-framework*
Because npm's OIDC trusted-publishing UI is unreliable, the workflow uses a granular access token for authentication.
- Go to https://www.npmjs.com/settings/jwitmann/tokens (Access Tokens).
- Create a Granular Access Token:
- Token name:
github-actions-opencode-dev-framework - Packages and scopes: choose Only select packages and scopes, then
pick
opencode-dev-framework - Permissions: Read and write
- Bypass 2FA: Enabled (required for automated publishing)
- Expiration: 90 days (or your preferred duration)
- Token name:
- Copy the token.
- In your GitHub repo, go to Settings → Secrets and variables → Actions.
- Create or update a repository secret named
NPM_TOKENwith the copied token.
Note: npm is deprecating 2FA-bypass granular access tokens for direct publishing around January 2027. Before then, migrate back to OIDC trusted publishing once npm's setup flow is stable.
Follow SemVer:
0.1.0— initial release.0.1.1— bug fixes.0.2.0— new features.
Release steps:
-
Run the release script, which handles everything:
npm run release # default: patch bump npm run release:minor # minor bump npm run release:major # major bump
The script runs the full validation suite, bumps the version in both
package.jsonandpackage-lock.jsonvianpm version, commits, and creates a git tag. -
Push the tag:
git push origin main --tags
-
CI validates and publishes automatically.
-
package.jsonname isopencode-dev-framework. -
package.jsonversion is updated. -
package.jsonrepository.urlexactly matches the GitHub repo. -
filesarray includesdist,bin,rules,templates. -
mainpoints todist/adapters/opencode/index.js(dual-harness layout;./dshexport servesdist/adapters/dsh/index.js). -
typespoints todist/adapters/opencode/index.d.ts. -
LICENSEexists. -
README.mdexists. - npm trusted publisher is configured for
jwitmann/opencode-dev-frameworkwith workflowci.yml. -
npm run buildsucceeds. -
npm run testsucceeds. -
.npmignoreorfilesarray excludes source/tests from the published package.
-
Visit https://www.npmjs.com/package/opencode-dev-framework and confirm the version is live.
-
In a scratch directory, create:
{ "$schema": "https://opencode.ai/config.json", "plugin": ["opencode-dev-framework"] } -
Run
opencodeand check the plugin loads without errors. -
Check OpenCode logs for plugin initialization message.
npm login defaults to web authentication and tries to open a browser. In a
headless shell, WSL, or SSH session this fails with:
npm error Set the BROWSER environment variable to your desired browser.
Use legacy terminal-based login instead:
npm login --auth-type=legacyThen enter your npm username, password, and 2FA/OTP code. Alternatively, print the web URL instead of opening a browser:
BROWSER=echo npm loginnpm error code ENEEDAUTH
npm error need auth This command requires you to be logged in to https://registry.npmjs.org/
With OIDC, this almost always means the trusted publisher configuration does not match the workflow run. Check:
- npmjs.com trusted publisher fields exactly match:
- organization/user:
jwitmann - repository:
opencode-dev-framework - workflow filename:
ci.yml(case-sensitive, including.yml)
- organization/user:
- The publish job has
permissions: id-token: write. - The workflow file exists on the commit that the tag points to.
package.jsonrepository.urlexactly matchesgit+https://github.com/jwitmann/opencode-dev-framework.git.- You are using GitHub-hosted runners. Self-hosted runners do not support OIDC trusted publishing.
Provenance is only auto-generated for public packages published from public repositories via OIDC. Private repos must disable provenance or publish manually.
The README and docs must clearly state:
- This is a community project, not affiliated with OpenCode or the original dev-framework team.
- The completion gate continues the turn via
syntheticat the idle boundary (session.hook("experimental.idle"), same execution), bounded bygate.max_blocks; theevent.subscribeidle net covers the boundaries the hook skips. The pre-flighttool.execute.beforedeny is the only true hard block. - Some features rely on OpenCode native config (
permission,formatter), which may evolve.