Contributing
The local development environment, common commands, the CI command line, how the docs site is built, the release process and the steps to add an npm package.
Requirements
| Tool | Version | Declared in |
|---|---|---|
| Node.js | 24 or later | engines field in package.json |
| pnpm | 11 | packageManager field in package.json |
| uv | See the config | required-version in scripts/ci/pyproject.toml |
Common commands
pnpm install
pnpm check # oxfmt --check, oxlint type checks and vitest; this is what CI runs
pnpm bundle # update dist/ and dsh/*/dist/, which DSH, the Cline plugin and the agent-stash CLI load
pnpm formatEach workspace package under packages/ has a bundle script whose dist/ output is committed. dsh/recall, dsh/autosuggest and dsh/kit are also workspace packages, and the root pnpm bundle builds them. The CI steps for bundles, upstream syncs, the plugin index, the docs site and npm run through the Python command line in scripts/ci (uv + Typer). The workflows call pnpm check and the release command pnpm tegami ci directly. You can run the same commands locally:
uv run --project scripts/ci ci --help
uv run --project scripts/ci ci bundle --check # rebuild dist/ of every workspace package, fail on differences
uv run --project scripts/ci ci npm status # list each package's npm versions and trusted publishing stateRepository layout
Docs site
The docs site is in docs/. It is a statically exported Fumadocs site. .github/workflows/pages.yml builds it with ci docs, generates the plugin index with ci plugin-index, and puts both into one GitHub Pages artifact. Pull requests that change docs/ only build a preview artifact; runs on main deploy it. The pages are in docs/content/docs/. Chinese pages are *.mdx files, and English pages are *.en.mdx files with the same names.
pnpm --filter agent-stash-docs dev # http://localhost:3883/agent-stash/
pnpm --filter agent-stash-docs build # outputs to docs/out/Screenshots and screen recordings go in docs/public/media/, their sizes are registered in docs/lib/media.ts, and pages show them with <Showcase>. English pages use the same steps recorded in the English interface, under scene names that end in -en. The contributors and page history at the end of the plugin and skills pages are read from Git at build time, so the build needs the full commit history. A new page shows them after its first commit.
Release
Version numbers follow semantic versioning. Tegami manages them, with its configuration in scripts/tegami.ts.
Write a changeset
Create a Markdown file in .tegami/. In the frontmatter, list each changed package with its bump type (major, minor or patch). The body holds the release notes, written in Chinese. The body needs at least one Markdown heading, because Tegami does not read files without a heading:
---
packages:
"@agent-stash/init": minor
---
## 新增 xxx 预设
- xxx 预设从上游每天同步。Merge the Version Packages PR
After a push to main, .github/workflows/release.yml opens a Version Packages PR that updates the version of each package and its CHANGELOG.md.
Publish to npm
After you merge this PR, the same workflow publishes the bumped packages to npm through npm trusted publishing (OIDC) with provenance, then creates the tags and GitHub releases: v<version> for @agent-stash/init and <name>@<version> for the other packages. The workflow waits until npm serves the new versions; the Pages workflow that runs next regenerates the plugin index and the docs site.
Trusted publishing only
The npm packages do not accept publishing with tokens that bypass 2FA. CI publishes only through trusted publishing.
The version badge in the README reads the latest GitHub release automatically.
Add an npm package
npm can configure a Trusted Publisher only for a package that already exists, so a new package first reserves its name with a one-time token:
Store a one-time token
On npmjs.com, generate a publish token for this step only and copy it to the clipboard. Then run uv run --project scripts/ci ci bootstrap store-token. It saves the clipboard content as the repository secret NPM_TOKEN and clears the clipboard.
Publish a placeholder version
Run uv run --project scripts/ci ci bootstrap publish --auth token. The release workflow uses the token to publish an empty 0.0.0-placeholder.<n> (dist-tag placeholder) for each package that has no regular version yet.
Add the Trusted Publisher
On the npm settings page of the package, add a Trusted Publisher: repository Alice39s/agent-stash, workflow release.yml.
Publish through OIDC
Run uv run --project scripts/ci ci bootstrap publish --auth oidc and check that ci npm status shows yes for trusted publishing.
Remove the token
Run uv run --project scripts/ci ci bootstrap remove-token. Revoke the token on npmjs.com and set the publishing access of the package to disallow tokens that bypass 2FA.
Last updated on