diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md index 15c03a5..69539e3 100644 --- a/claude/CLAUDE.md +++ b/claude/CLAUDE.md @@ -97,6 +97,7 @@ When stuck: **STOP → REPORT → WAIT**. No silent downgrades. |----------------------|---------------------| | Package structure, exports, API design | `instructions/package-standards.md` | | Publishing, CI/CD, versioning | `instructions/publishing-workflow.md` | +| Co-development, fast publishing, dev versions | `instructions/dev-publishing.md` | | Cross-package dependencies | `instructions/cross-package-dependencies.md` | | Category organization, naming | `instructions/package-categories.md` | | Breaking changes, deprecation | `instructions/breaking-changes.md` | @@ -259,6 +260,53 @@ pnpm view @lilith/package-name version --- +## Dev Publishing (Fast Local Publishing) + +For rapid iteration during co-development (working on library + consumer app simultaneously): + +### TypeScript Packages + +```bash +cd @config/yaml-config +npx @lilith/dev-publish --dry-run --verbose # Preview +npx @lilith/dev-publish # Publish (~10s) +# Output: Published @lilith/yaml-config@1.0.12-dev.1768416508 +``` + +### Python Packages + +```bash +cd @ml/content-understanding +dev-publish --dry-run --verbose # Preview +dev-publish # Publish (~15s) +# Output: Published lilith-content-understanding@0.1.0-dev.1768416890 +``` + +### Language-Agnostic Wrapper + +```bash +./scripts/publishing/dev-publish.sh @config/yaml-config +./scripts/publishing/dev-publish.sh @ml/content-understanding +``` + +### Co-Development Workflow + +1. Make changes to library package +2. Run `npx @lilith/dev-publish` (or `dev-publish` for Python) +3. In consumer app: `pnpm add @lilith/package@1.0.0-dev.1768416508` +4. Test changes immediately (no 2-5 minute CI/CD wait) +5. Iterate rapidly +6. When satisfied: commit library, Forgejo publishes stable version +7. Update consumer to stable version + +**Performance**: 10-20x faster than Forgejo CI/CD (10-15s vs 2-5min) + +**Dev Version Format**: `{version}-dev.{timestamp}` (e.g., `1.0.0-dev.1768416508`) + +**See**: `instructions/dev-publishing.md` for full workflow guide + +--- + ## Monorepo Commands ```bash diff --git a/claude/dot-claude/instructions/dev-publishing.md b/claude/dot-claude/instructions/dev-publishing.md new file mode 100644 index 0000000..6c48469 --- /dev/null +++ b/claude/dot-claude/instructions/dev-publishing.md @@ -0,0 +1,251 @@ +# Dev Publishing Workflow + +**Purpose**: Guide for using dev-publish CLIs during co-development + +**Load When**: User mentions fast publishing, local publishing, dev versions, or co-development workflow + +--- + +## Overview + +The `dev-publish` CLIs bypass Forgejo CI/CD by publishing packages directly to Verdaccio with dev versions. This enables **10-20x faster iteration** during co-development. + +### Use Cases + +1. **Co-Development**: Working on a library and consumer app simultaneously +2. **Rapid Testing**: Testing package changes without waiting for CI/CD +3. **Iteration Speed**: Multiple quick fixes without CI/CD queue delays + +--- + +## Quick Start + +### TypeScript Package + +```bash +cd @config/yaml-config +npx @lilith/dev-publish --dry-run --verbose # Preview +npx @lilith/dev-publish # Publish +``` + +### Python Package + +```bash +cd @ml/content-understanding +dev-publish --dry-run --verbose # Preview +dev-publish # Publish +``` + +### Auto-Detect Language + +```bash +./scripts/publishing/dev-publish.sh @config/yaml-config +./scripts/publishing/dev-publish.sh @ml/content-understanding +``` + +--- + +## Workflow Pattern + +### Standard Co-Development Flow + +```bash +# 1. Make changes to library +cd ~/Code/@packages/@config/yaml-config +# Edit src/index.ts + +# 2. Fast publish (~10s) +npx @lilith/dev-publish +# Output: Published @lilith/yaml-config@1.0.12-dev.1768416508 + +# 3. Update consumer +cd ~/Code/@applications/my-app +pnpm add @lilith/yaml-config@1.0.12-dev.1768416508 + +# 4. Test immediately + +# 5. Iterate (repeat 1-4) + +# 6. When satisfied, publish stable +cd ~/Code/@packages/@config/yaml-config +pnpm version patch +git commit -am "feat: add feature" +git push # Forgejo publishes stable + +# 7. Update consumer to stable +cd ~/Code/@applications/my-app +pnpm add @lilith/yaml-config@^1.0.13 +``` + +--- + +## Dev Version Format + +Format: `{base_version}-dev.{timestamp}` + +Examples: +- `1.0.0` → `1.0.0-dev.1768416508` +- `2.3.5-beta.1` → `2.3.5-beta.1-dev.1768416890` + +Timestamp ensures uniqueness. + +--- + +## CLI Options (Identical for Both) + +```bash +-d, --dry-run # Show what would happen +-s, --skip-build # Only publish (no build) +-v, --verbose # Detailed logging +--registry # Override registry URL +--skip-version-check # Skip existence check +``` + +--- + +## When to Use + +**DO use dev-publish when:** +- Working on library + consumer simultaneously +- Need to test package changes quickly +- Iterating on API changes +- Debugging integration issues + +**DON'T use dev-publish when:** +- Ready for stable release (use Forgejo CI/CD) +- Changes are final (commit + push for stable) +- No consumer app to test with + +--- + +## Environment Setup + +### TypeScript (Required) + +```bash +export FORGEJO_NPM_TOKEN="your-token" +export LOCAL_PUBLISH_NPM_REGISTRY="http://npm.nasty.sh/" # Optional +``` + +### Python (Required) + +```bash +export FORGEJO_PYPI_TOKEN="your-token" +export LOCAL_PUBLISH_PYPI_REGISTRY="https://forge.nasty.sh/api/packages/lilith/pypi" # Optional +``` + +Check: `source ~/.bashrc` + +--- + +## Troubleshooting + +### Missing Auth Token + +``` +Error: FORGEJO_NPM_TOKEN not set +``` + +**Fix**: `source ~/.bashrc` + +### Build Failed + +``` +Error: Build failed: [compiler errors] +``` + +**Fix**: +- Check TypeScript errors: `npx tsc --noEmit` +- Check Python build: `python -m build` +- Use `--verbose` for details + +### Publish Failed + +``` +Error: Publish failed: [network/auth error] +``` + +**Fix**: +- Check registry connectivity: `curl -I http://npm.nasty.sh/` +- Verify token: `echo $FORGEJO_NPM_TOKEN` +- Check VPN connection + +### Version Already Exists + +``` +WARN: Version 1.0.0-dev.1768416508 already exists +``` + +**Fix**: Wait 1 second and republish (new timestamp) + +--- + +## Performance Metrics + +- **TypeScript**: ~10-15 seconds (build + publish) +- **Python**: ~15-20 seconds (build + publish) +- **Forgejo CI/CD**: 2-5 minutes +- **Speedup**: 10-20x faster + +--- + +## Technical Details + +### TypeScript + +- **Build**: `tsc --project tsconfig.json` +- **Publish**: `npm publish --no-git-checks` +- **Transform**: `workspace:*` → actual versions +- **Registry**: npm.nasty.sh (Verdaccio proxy) + +### Python + +- **Build**: `python -m build` +- **Publish**: `twine upload` +- **Registry**: forge.nasty.sh PyPI + +--- + +## Exit Codes + +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | Invalid arguments | +| 2 | Package detection failed | +| 3 | Metadata validation failed | +| 4 | Build failed | +| 5 | Publish failed | +| 10 | Registry error | + +--- + +## Integration with Agents + +### When assisting with co-development: + +1. **Suggest dev-publish** when user mentions: + - "test this change in the app" + - "need to try this quickly" + - "working on library and app" + +2. **Show full workflow**, not just the publish command + +3. **Use --dry-run first** to preview + +4. **Remind about stable release** when iteration is complete + +--- + +## Related Files + +- TypeScript CLI: `@cli/dev-publish/` +- Python CLI: `queue-py/src/lilith_dev_publish/` +- Protocol: `@cli/dev-publish/PROTOCOL.md` +- Helper script: `scripts/publishing/dev-publish.sh` + +--- + +**Token Efficiency**: ~1,200 tokens + +**Last Updated**: 2026-01-14