OverviewFilesCommitsIssuesDocsReleasesPeers

wirecore commits / a457206

Add comprehensive Pear staging & seeding guide
Complete reference documentation for managing Pear app deployment: - Quick reference for all Pear CLI commands - Complete workflow for staging and seeding - Troubleshooting guide for common issues - Production deployment patterns (systemd, Docker, nohup) - Security considerations and key management - Monitoring and debugging techniques - Alternative deployment with pear dump Key tools documented: - pear-stage, pear-seed, pear-dump - pear-inspect for remote debugging - pear-info for metadata inspection - All 72 Pear-related holepunchto packages Installation link: pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo This guide serves as a skill-like reference for future Pear app development and deployment. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
a457206c71dffe323757f4015d196c889f5f8805
by plankatron <fleeky@gmail.com> · 2026-01-20T20:34:04.000Z

Changed files (1) +505 -0

PEAR_STAGING_GUIDE.md +505 -0
……@@ -0,0 +1,505 @@
1# Pear Staging & Seeding Guide for Wirecore
2
3**Quick Reference for managing Pear app deployment**
4
5## 📦 Installation Link
6
7```
8pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo
9```
10
11Anyone can install wirecore with:
12```bash
13pear run pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo init
14```
15
16## 🔧 Available Pear Tools (from holepunchto ecosystem)
17
18### Core Tools
19- **pear** - Main CLI with all commands built-in
20- **pear-stage** - NPM package for programmatic staging
21- **pear-seed** - NPM package for programmatic seeding
22- **pear-dump** - Extract app from pear:// link to local directory
23- **pear-inspect** - Remote debugging via Chrome DevTools Protocol
24- **pear-info** - View app metadata and manifests
25- **pear-run** - Programmatically run Pear apps
26- **pear-link** - Parse and construct pear:// URLs
27
28### Development Tools
29- **pear-doctor** - Diagnostic and troubleshooting desktop app
30- **pear-pack** - Bundle and prebuild generation
31- **pear-build** - Build application shells
32
33## 📋 Pear CLI Commands
34
35### Essential Commands
36
37| Command | Purpose | Example |
38|---------|---------|---------|
39| `pear init` | Create project structure | `pear init -t terminal -y` |
40| `pear stage <channel> .` | Stage changes | `pear stage wirecore .` |
41| `pear seed <channel> .` | Seed to DHT | `pear seed wirecore .` |
42| `pear run <link>` | Run from P2P | `pear run pear://...` |
43| `pear release <channel>` | Mark production version | `pear release wirecore` |
44| `pear info <link>` | View app metadata | `pear info pear://...` |
45| `pear dump <link> <dir>` | Extract to local | `pear dump pear://... /opt/app` |
46
47### Useful Flags
48
49- `--json` - JSON output (for staging/seeding)
50- `--dev` or `-d` - Development mode (for run)
51- `--dry-run` - Preview changes without staging
52- `--verbose` - Detailed output
53- `--checkout=n` - Specific version number
54- `--no-ask` - Suppress permission dialogs
55
56## 🚀 Wirecore Staging & Seeding Workflow
57
58### Initial Setup (First Time)
59
60```bash
61cd /storage/projects/code/hypercore-kb/hyper-fleeky/repos/wirecore/pear-app
62
63# Verify package.json has pear config
64cat package.json # Should have "pear": { "name": "wirecore-pear", "type": "terminal" }
65
66# Verify .pearignore excludes local data but NOT node_modules
67cat .pearignore
68```
69
70**Critical**: `.pearignore` must NOT ignore `node_modules/` due to module resolution bugs under pear:// protocol.
71
72### Stage Changes
73
74```bash
75# First stage (creates channel and key)
76pear stage wirecore .
77
78# Subsequent stages (updates version)
79pear stage wirecore .
80
81# View changes before staging
82pear stage --dry-run wirecore .
83
84# JSON output for automation
85pear stage --json wirecore .
86```
87
88**Output**:
89- Key: `zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo`
90- Link: `pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo`
91- Version number (incrementing)
92
93### Seed to Network
94
95```bash
96# Start seeding (runs in foreground)
97pear seed wirecore .
98
99# Background seeding (recommended for production)
100pear seed wirecore . &
101
102# JSON output
103pear seed --json wirecore .
104```
105
106**Note**: Seed keeps running to make app available to peers. For production, run as systemd service or use `nohup`.
107
108### Mark Production Release
109
110```bash
111# Mark current version as production release
112pear release wirecore
113
114# This updates the "release" pointer that users see by default
115```
116
117### Test Installation
118
119```bash
120# Test in /tmp (clean environment)
121cd /tmp
122pear run pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo init
123
124# Test specific version
125pear run --checkout=2218 pear://... init
126
127# Test development version (latest)
128pear run --dev pear://... init
129```
130
131## 📝 package.json Configuration
132
133```json
134{
135 "name": "wirecore-pear",
136 "version": "1.0.0",
137 "type": "module",
138 "main": "index.js",
139 "pear": {
140 "name": "wirecore-pear",
141 "type": "terminal",
142 "gui": {
143 "backgroundColor": "#1e1e1e"
144 }
145 },
146 "scripts": {
147 "dev": "pear run -d .",
148 "stage": "pear stage wirecore .",
149 "seed": "pear seed wirecore .",
150 "release": "pear release wirecore"
151 }
152}
153```
154
155**Important Fields**:
156- `"type": "module"` - Enable ESM imports
157- `"pear"."type"` - Can be "terminal" or "desktop"
158- `"pear"."name"` - Displayed name in Pear ecosystem
159
160## 📄 .pearignore Configuration
161
162```
163# CRITICAL: Do NOT ignore node_modules
164# (module resolution bug under pear:// protocol)
165
166# Development files
167.git
168.gitignore
169*.log
170.DS_Store
171
172# Test files
173test/
174
175# Documentation
176README.md
177docs/
178
179# Local data (per-installation)
180wirecore-storage/
181test-storage/
182
183# Build artifacts
184*.swp
185*.swo
186*~
187```
188
189## 🐛 Common Issues & Solutions
190
191### Issue 1: Module Resolution Errors
192
193**Error**: `MODULE_NOT_FOUND: Cannot find module 'fs'`
194
195**Cause**: Dynamic imports (`await import('fs')`) don't work in Bare/Pear runtime
196
197**Solution**: Use static imports or try-catch patterns
198```javascript
199// BAD - doesn't work in Pear
200const fs = await import('fs')
201
202// GOOD - use try-catch
203try {
204 store = new Corestore(path)
205 await store.ready()
206} catch (err) {
207 // Handle missing storage
208}
209```
210
211### Issue 2: node_modules Not Found
212
213**Error**: Dependencies missing when running from pear:// link
214
215**Cause**: `.pearignore` includes `node_modules/`
216
217**Solution**: Remove `node_modules` from `.pearignore`
218
219### Issue 3: Staging from Wrong Directory
220
221**Error**: `"/tmp/package.json" not found`
222
223**Cause**: Running `pear stage` from different directory than project root
224
225**Solution**: Always `cd` to project directory first
226```bash
227cd /storage/projects/code/hypercore-kb/hyper-fleeky/repos/wirecore/pear-app
228pear stage wirecore .
229```
230
231### Issue 4: Channel Name Required
232
233**Error**: `A key or the channel name must be specified`
234
235**Cause**: First `pear stage` needs channel name
236
237**Solution**: Provide channel name
238```bash
239# First time
240pear stage wirecore .
241
242# Subsequent (can use key or channel name)
243pear stage wirecore .
244pear stage pear://zupx... .
245```
246
247### Issue 5: Seed Not Making App Available
248
249**Symptom**: `pear run pear://...` times out or fails to download
250
251**Causes**:
2521. Seed process not running
2532. Firewall blocking DHT ports
2543. Not enough time for DHT propagation
255
256**Solutions**:
257```bash
258# Verify seed is running
259ps aux | grep "pear seed"
260
261# Re-seed
262pear seed wirecore . &
263
264# Wait 30-60 seconds for DHT propagation
265
266# Test locally first
267pear run --dev pear://... init
268```
269
270## 🔄 Update Workflow
271
272```bash
273cd pear-app
274
275# 1. Make code changes
276vim index.js
277
278# 2. Test locally
279npm run dev -- init
280npm run dev -- post "test"
281
282# 3. Stage changes
283pear stage wirecore .
284# Output: Latest version is now 2219
285
286# 4. Seed automatically updates (if already running)
287# Or restart seed:
288killall pear-seed # if needed
289pear seed wirecore . &
290
291# 5. Mark as production release
292pear release wirecore
293
294# 6. Test installation
295cd /tmp && rm -rf test-wirecore
296pear run pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo init
297```
298
299## 🏭 Production Seeding
300
301### Systemd Service (Recommended)
302
303Create `/etc/systemd/system/wirecore-seed.service`:
304
305```ini
306[Unit]
307Description=Wirecore Pear Seeding Service
308After=network.target
309
310[Service]
311Type=simple
312User=pear-seed
313Group=pear-seed
314WorkingDirectory=/opt/wirecore-pear
315ExecStart=/usr/local/bin/pear seed wirecore .
316Restart=always
317RestartSec=10
318
319[Install]
320WantedBy=multi-user.target
321```
322
323Enable and start:
324```bash
325sudo systemctl daemon-reload
326sudo systemctl enable wirecore-seed
327sudo systemctl start wirecore-seed
328sudo systemctl status wirecore-seed
329```
330
331### Docker Container
332
333```dockerfile
334FROM node:20
335RUN npm install -g pear
336WORKDIR /app
337COPY pear-app/ .
338CMD ["pear", "seed", "wirecore", "."]
339```
340
341### Background Process with nohup
342
343```bash
344cd pear-app
345nohup pear seed wirecore . > seed.log 2>&1 &
346echo $! > seed.pid
347
348# Stop seeding
349kill $(cat seed.pid)
350```
351
352## 📊 Monitoring & Debugging
353
354### Check Staging Info
355
356```bash
357pear info pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo
358
359# With flags
360pear info --metadata pear://...
361pear info --manifest pear://...
362pear info --json pear://...
363```
364
365### View Specific Version
366
367```bash
368# List versions
369pear info --json pear://... | jq '.versions'
370
371# Run specific version
372pear run --checkout=2218 pear://... init
373```
374
375### Remote Debugging with pear-inspect
376
377```bash
378# On target machine
379pear run --inspect pear://... init
380
381# On development machine
382npm install -g pear-inspect
383pear-inspect <connection-string>
384# Opens Chrome DevTools for remote debugging
385```
386
387### Extract App for Inspection
388
389```bash
390# Download to local directory
391pear dump pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo /tmp/wirecore-inspect
392
393# List files without downloading
394pear dump --list pear://...
395
396# Inspect contents
397cd /tmp/wirecore-inspect
398ls -la
399cat package.json
400```
401
402## 🔐 Security Considerations
403
404### Key Management
405
406- **Channel Key**: `zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo`
407- Stored in: `~/.config/pear/app-storage/`
408- Backup: Store key securely offline
409- Recovery: No recovery if lost (immutable)
410
411### Permissions
412
413Pear apps request capabilities:
414- Network access
415- File system access
416- Subprocess execution
417
418Users see permission prompts on first run.
419
420### Signed Releases
421
422```bash
423# Mark trusted version
424pear release wirecore
425
426# Users get this version by default
427pear run pear://... # Uses release version
428```
429
430## 📦 Alternative: Local Directory Deployment
431
432For production with module resolution issues:
433
434```bash
435# 1. Dump to local directory
436pear dump pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo /opt/wirecore
437
438# 2. Run from local directory (more reliable)
439pear run /opt/wirecore init
440
441# 3. Update
442pear dump --force pear://... /opt/wirecore
443```
444
445**Pros**: Avoids pear:// module resolution bugs
446**Cons**: Requires manual update process
447
448## 🎯 Quick Commands Reference
449
450```bash
451# Development
452npm run dev -- init # Local test
453npm run stage # Stage changes
454npm run seed # Seed to network
455
456# Installation (users)
457pear run pear://zupx... init # Install and init
458pear run pear://zupx... post "msg" # Use command
459pear run pear://zupx... timeline # View timeline
460
461# Management
462pear info pear://zupx... # View metadata
463pear release wirecore # Mark production
464pear dump pear://zupx... /tmp/app # Extract locally
465
466# Debugging
467pear run --dev pear://zupx... init # Dev version
468pear run --checkout=2218 pear://... # Specific version
469pear-inspect <connection> # Remote debug
470```
471
472## 📚 Additional Resources
473
474- **Pear Docs**: https://docs.pears.com
475- **Holepunchto GitHub**: https://github.com/holepunchto
476- **Pear CLI Reference**: `/storage/projects/code/hypercore-kb/holepunchto/pear-docs/reference/cli.md`
477- **Deployment Guide**: `/storage/projects/code/hypercore-kb/holepunchto/deployment/pear-apps.md`
478- **Our Lessons Learned**: `hyper-fleeky/pear-deployment-lessons.md`
479
480## 🔧 Troubleshooting Checklist
481
482- [ ] In correct directory? (`pwd` shows pear-app/)
483- [ ] package.json has pear config?
484- [ ] .pearignore excludes local data but NOT node_modules?
485- [ ] Seed process running? (`ps aux | grep seed`)
486- [ ] DHT propagation time waited? (30-60 seconds)
487- [ ] Firewall allows UDP? (Hyperswarm needs it)
488- [ ] Tested locally first? (`npm run dev`)
489- [ ] Latest pear version? (`npx pear --version`)
490
491## 🎉 Success Criteria
492
493Working installation when:
494- ✅ `pear stage wirecore .` completes successfully
495- ✅ `pear seed wirecore .` runs without errors
496- ✅ `pear info pear://...` shows metadata
497- ✅ `cd /tmp && pear run pear://... init` creates identity
498- ✅ `pear run pear://... post "test"` posts message
499- ✅ `pear run pear://... timeline` shows timeline
500
501---
502
503**Last Updated**: Phase 1.8 - Pear Packaging Complete
504**Pear Link**: `pear://zupx3qzpwj61hdt1bxanabctcyxqqu3arogctwim4qt3wfbzn4bo`
505**Status**: ✅ Successfully staged, seeded, and tested