npm Package Publishing

How to publish @zaflun/lumio-* packages to npmjs.com.

Packages

Package	npm Name	Directory
Protocol	@zaflun/lumio-protocol	packages/protocol
Extension Types	@zaflun/lumio-extension-types	packages/extension-types
SDK	@zaflun/lumio-sdk	packages/sdk
CLI	@zaflun/lumio-cli	packages/cli
Agent Skill	@zaflun/lumio-agent-skill	packages/agent-skill

All packages use SemVer (1.0.0, 1.0.1, 1.1.0), NOT the Lumio YYYY.M.PATCH format.

Prerequisites (one-time setup)

1. npm Organization: Create @zaflun org at npmjs.com/org/create
2. npm Token: Create an "Automation" token at npmjs.com → Avatar → Access Tokens
3. GitHub Secret: Add NPM_TOKEN to the repo: Settings → Secrets → Actions → New secret

Publishing a Single Package

Via Tag (recommended)

# 1. Bump version in package.json
cd packages/protocol
# Edit "version": "1.0.0" → "1.0.1"

# 2. Commit
git add packages/protocol/package.json
git commit -m "chore(protocol): bump version to 1.0.1"

# 3. Create tag (format: @zaflun/{package-name}@{version})
git tag "@zaflun/lumio-protocol@1.0.1"

# 4. Push (triggers publish-npm.yml workflow)
git push origin next --tags

The workflow runs: Install → Build → Test → Typecheck → Publish.

Via Manual Dispatch

1. Go to GitHub → Actions → "Publish npm Package"
2. Click "Run workflow"
3. Select the package from the dropdown (e.g. protocol)
4. Click "Run workflow"

Via gh CLI

gh workflow run "Publish npm Package" --field package=protocol

Publishing All Packages

Use the "Publish All npm Packages" workflow. It publishes in dependency order:

Layer 1 (parallel):  protocol + extension-types + agent-skill
Layer 2 (waits):     sdk (depends on protocol + extension-types)
                     cli (depends on extension-types)

Run via GitHub UI

1. GitHub → Actions → "Publish All npm Packages"
2. Click "Run workflow"
3. Dry run checkbox:
   • ☑ Checked = build + test only, no publish (for verification)
   • ☐ Unchecked = actually publish to npm

Run via gh CLI

# Dry run (test only):
gh workflow run "Publish All npm Packages" --field dry_run=true

# Actual publish:
gh workflow run "Publish All npm Packages" --field dry_run=false

Dependency Order

When publishing for the first time or after breaking changes, publish in this order:

Order	Package	Depends On
1	@zaflun/lumio-protocol	—
2	@zaflun/lumio-extension-types	—
3	@zaflun/lumio-agent-skill	—
4	@zaflun/lumio-sdk	protocol + extension-types
5	@zaflun/lumio-cli	extension-types

The "Publish All" workflow handles this automatically via needs: dependencies.

Version Bumping

# Patch (bug fix): 1.0.0 → 1.0.1
# Minor (new feature): 1.0.0 → 1.1.0
# Major (breaking change): 1.0.0 → 2.0.0

Edit "version" in the package's package.json directly. No automated version bump tool.

Verifying a Release

After publish, verify on npm:

npm view @zaflun/lumio-protocol
npm view @zaflun/lumio-sdk version

Or visit: https://www.npmjs.com/package/@zaflun/lumio-sdk

Testing Locally Before Publish

# Build
cd packages/sdk && pnpm build

# Test
pnpm test

# Typecheck
pnpm typecheck

# Or use the "Publish All" workflow with dry_run=true

Workspace Dependencies

Packages reference each other via "workspace:*" in package.json:

"dependencies": {
  "@zaflun/lumio-protocol": "workspace:*"
}

When pnpm publish runs, it automatically replaces workspace:* with the actual version (e.g. ^1.0.0). This means the referenced package must already be published on npm.

Troubleshooting

"No projects matched the filters"

The package name in pnpm-workspace.yaml doesn't match. Verify:

• packages/* is listed in pnpm-workspace.yaml
• The "name" field in package.json matches @zaflun/lumio-*

"402 Payment Required"

The @zaflun npm org doesn't exist or the token doesn't have publish access. Create the org at npmjs.com.

"403 Forbidden"

The npm token doesn't have permission to publish under @zaflun. Check:

• Token type is "Automation" (not "Read-only")
• Token belongs to a user who is a member of the @zaflun org

"EPUBLISHCONFLICT" / "Cannot publish over existing version"

The version already exists on npm. Bump the version number and try again.

Workflow Files

Workflow	File	Trigger
Single package	.github/workflows/publish-npm.yml	Tag @zaflun/*@* or manual dispatch
All packages	.github/workflows/publish-npm-all.yml	Manual dispatch only