# Dev-Publish Quick Reference

## Common Usage Patterns

### Basic Publishing

```bash
# From package directory
cd @config/yaml-config
npx @lilith/dev-publish

# From anywhere
npx @lilith/dev-publish @config/yaml-config
```

### With Options

```bash
# Dry run - see what would happen
npx @lilith/dev-publish --dry-run

# Verbose - detailed logging
npx @lilith/dev-publish --verbose

# Skip build - only publish
npx @lilith/dev-publish --skip-build

# Custom registry
npx @lilith/dev-publish --registry http://localhost:4873

# Combine options
npx @lilith/dev-publish --dry-run --verbose
```

### Co-Development Workflow

**Scenario**: Updating `@config/yaml-config` while working on a consumer app

1. Make changes to library:
   ```bash
   cd @config/yaml-config
   # Edit src/index.ts
   ```

2. Fast publish with dev version (~10 seconds):
   ```bash
   npx @lilith/dev-publish
   # Output: Published @lilith/yaml-config@1.0.12-dev.1768416508
   ```

3. Update consumer app:
   ```bash
   cd ~/Code/@applications/my-app
   pnpm add @lilith/yaml-config@1.0.12-dev.1768416508
   ```

4. Test changes immediately

5. Iterate (repeat steps 1-4)

6. When satisfied, publish stable version:
   ```bash
   cd @config/yaml-config
   pnpm version patch  # → 1.0.13
   git commit -am "feat: add new feature"
   git push  # Forgejo CI publishes stable 1.0.13
   ```

7. Update consumer to stable:
   ```bash
   cd ~/Code/@applications/my-app
   pnpm add @lilith/yaml-config@^1.0.13
   ```

### Troubleshooting

**Error: FORGEJO_NPM_TOKEN not set**
```bash
source ~/.bashrc
# Or set manually:
export FORGEJO_NPM_TOKEN="your-token-here"
```

**Build Failed**
```bash
# Check TypeScript errors
npx tsc --noEmit

# Try with verbose output
npx @lilith/dev-publish --verbose
```

**Publish Failed**
```bash
# Check registry connectivity
curl -I http://npm.black.lan/

# Verify token is valid
echo $FORGEJO_NPM_TOKEN
```

## Environment Variables

**Required:**
- `FORGEJO_NPM_TOKEN` - npm registry authentication token

**Optional:**
- `LOCAL_PUBLISH_NPM_REGISTRY` - Registry URL (default: `http://npm.black.lan/`)

## 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 |

## Dev Version Format

Format: `{base_version}-dev.{timestamp}`

Examples:
- `1.0.0` → `1.0.0-dev.1768416508`
- `2.3.5` → `2.3.5-dev.1768416890`

Timestamp ensures each build gets a unique version.

## Performance

- **Build + Publish**: ~10-15 seconds
- **vs Forgejo CI/CD**: 2-5 minutes
- **Speedup**: 10-20x faster iteration

## See Also

- [Full README](./README.md)
- [PROTOCOL.md](./PROTOCOL.md)
- [Python CLI](../../queue-py/src/lilith_dev_publish/)