feat: npm publish workflow with OIDC trusted publishing (#358)

* Add npm publish workflow and release infrastructure

- Add .github/workflows/npm-publish.yml for automated npm publishing on GitHub releases
- Update CI to verify library build (npm run build:lib) and package contents
- Add CHANGELOG.md for version history tracking
- Update README.md with npm installation and usage documentation

Closes #197

Co-authored-by: openhands <openhands@all-hands.dev>

* correct package version

* chore: update npm-publish workflow for trusted publishing

- Remove NODE_AUTH_TOKEN secret dependency
- Keep id-token: write permission for OIDC
- Add provenance flag for npm attestations
- Add comment explaining trusted publisher setup on npmjs.com

Co-authored-by: openhands <openhands@all-hands.dev>

* feat: add CLI entry point for npx execution

- Add bin/agent-canvas.mjs as executable CLI
- Add bin field to package.json for npm bin linking
- Include bin/ and build/ directories in published files
- CLI serves the built application with SPA routing support
- Supports --port, --host, and --help options

Co-authored-by: openhands <openhands@all-hands.dev>

* refactor: consolidate npm executable to use dev-docker infrastructure

- bin/agent-canvas.mjs now uses dev-with-automation.mjs main() with
  dev-docker.mjs's Docker-specific agent-server starter
- Added --static and --static-dir support to dev-with-automation.mjs
  so the npm executable serves pre-built static assets instead of Vite
- Added startStaticFrontend() function that uses static-server.mjs
- npm executable runs full stack: Docker agent-server + uvx automation
  backend + static frontend + ingress proxy

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: include scripts/ in npm package files

The bin/agent-canvas.mjs executable imports from scripts/dev-with-automation.mjs
and scripts/dev-docker.mjs, so the scripts directory must be included in the
published package.

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: address review comments

- Fix CHANGELOG.md version mismatch: 1.6.0 -> 1.0.0-alpha.1 to match package.json
- Add NODE_AUTH_TOKEN env var to npm-publish workflow for authentication
- Add CLI entry point mention to CHANGELOG

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: use OIDC trusted publishing (no NPM_TOKEN needed)

npm trusted publishing with OIDC doesn't require NODE_AUTH_TOKEN.
Instead it uses short-lived OIDC tokens generated by GitHub Actions.

Requirements:
- id-token: write permission (already set)
- npm CLI 11.5.1+ (added npm install -g npm@latest step)
- Trusted publisher configured on npmjs.com

See: https://docs.npmjs.com/trusted-publishers/

Co-authored-by: openhands <openhands@all-hands.dev>

* chore: bump version to 1.0.0-alpha.2

Co-authored-by: openhands <openhands@all-hands.dev>

* Build app assets before npm publish

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: use Node 24 for npm trusted publishing

Trusted publishing requires Node 22.14.0+ and npm 11.5.1+.
Node 24 ships with npm 11.x which meets the requirement.
Node 22.12.0 (previous) ships with npm 10.x which doesn't support OIDC.

Also removed the manual npm upgrade step since Node 24 includes
a compatible npm version by default.

Co-authored-by: openhands <openhands@all-hands.dev>

* chore: align all workflows to Node 24 and regenerate lockfile

- Update ci.yml to use Node 24
- Update sdk-version-sync.yml to use Node 24
- Regenerate package-lock.json with npm 11.12.1

All workflows now use Node 24 which ships with npm 11.x,
required for OIDC trusted publishing (npm 11.5.1+).

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: remove incorrect LLM env vars from CLI help

LLM_MODEL and LLM_API_KEY were listed in the help text but aren't
actually used by the scripts. LLM settings are configured through
the web UI settings page instead.

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: address PR review feedback

Critical fixes:
- Guard prepare script to only run in dev context (check for ../.git)
- Add missing existsSync import in dev-with-automation.mjs

Workflow improvements:
- Update checkout/setup-node actions to v6 for consistency
- Add npm version validation (must be 11.5.1+ for trusted publishing)
- Add package version validation (must match release tag)

CLI improvements:
- Add try-catch for dynamic imports with helpful error message
- Use console.error directly instead of imported logError/c

Documentation:
- Fix README export names: ChatInterface→ChatPanel, Terminal→TerminalPanel
- Add dist/ to .gitignore

Co-authored-by: openhands <openhands@all-hands.dev>

* ci: trigger npm publish on tag push instead of release

Simpler workflow - just push a tag like v1.0.0-alpha.2 to publish.

Co-authored-by: openhands <openhands@all-hands.dev>

* chore: remove tarball and add *.tgz to gitignore

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: npm publish errors

1. Fix bin path - remove './' prefix (npm pkg fix)
2. Add --tag for prerelease versions (alpha/beta/rc)

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: add repository field for npm provenance verification

npm provenance requires repository.url to match the GitHub Actions
source. Also added description, homepage, and bugs fields.

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: add .npmignore to include build/ directory in package

npm respects .gitignore when there's no .npmignore, which was
excluding the build/ directory from the published package.

The .npmignore explicitly lists what to exclude (src/, tests/,
dev configs) while allowing build/ and dist/ to be included.

Co-authored-by: openhands <openhands@all-hands.dev>

* fix: correct BUILD_DIR path in CLI entry point

The react-router build outputs to build/ directly (not build/client/)
because react-router.config.ts has unpackClientDirectory that moves
files from build/client/ to build/ and removes the client/ folder.

Co-authored-by: openhands <openhands@all-hands.dev>

* chore: bump version to 1.0.0-alpha.3

Co-authored-by: openhands <openhands@all-hands.dev>

---------

Co-authored-by: openhands <openhands@all-hands.dev>

.npmignore

@@ -0,0 +1,51 @@
+# npm ignore file - overrides .gitignore for npm publish
+# We need to INCLUDE build/ and dist/ which are in .gitignore
+
+# Source files (not needed in package)
+src/
+__tests__/
+tests/
+*.test.ts
+*.test.tsx
+*.spec.ts
+
+# Development config
+.github/
+.husky/
+.openhands/
+.agents/
+.vscode/
+*.config.ts
+*.config.js
+*.config.mjs
+tsconfig*.json
+eslint.config.mjs
+.eslintrc*
+.prettierrc*
+vitest.setup.ts
+
+# Development docs
+DEVELOPMENT.md
+AGENTS.md
+CHANGELOG.md
+
+# Generated files we don't need
+public/locales/
+src/i18n/declaration.ts
+.env*
+.envrc
+
+# Test artifacts
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/
+coverage/
+
+# Misc
+node_modules/
+*.tgz
+.react-router/
+.vercel
+ralph/
+artifacts/

bin/agent-canvas.mjs

@@ -16,7 +16,8 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const BUILD_DIR = join(__dirname, "..", "build", "client");
+// Build output is in build/ (not build/client/) - see react-router.config.ts unpackClientDirectory
+const BUILD_DIR = join(__dirname, "..", "build");
 
 // Check for help flag first
 const args = process.argv.slice(2);

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@openhands/agent-canvas",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@openhands/agent-canvas",
-      "version": "1.0.0-alpha.2",
+      "version": "1.0.0-alpha.3",
       "license": "MIT",
       "dependencies": {
         "@heroui/react": "2.8.10",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/agent-canvas",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.3",
   "description": "Agent Canvas UI for OpenHands - run AI coding agents with a visual interface",
   "license": "MIT",
   "private": false,