chore: 🔧 Update files
This commit is contained in:
Lilith
parent
d0bfbed624
commit
0cf1c0ea99
2 changed files with 299 additions and 0 deletions
|
|
@ -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
|
||||
|
|
|
|||
251
claude/dot-claude/instructions/dev-publishing.md
Normal file
251
claude/dot-claude/instructions/dev-publishing.md
Normal file
|
|
@ -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 <url> # 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
|
||||
Loading…
Add table
Reference in a new issue