specweave 1.0.94 → 1.0.95
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "specweave",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.95",
|
|
4
4
|
"description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -62,12 +62,22 @@ if [ -f "$REFLECT_HOOK" ]; then
|
|
|
62
62
|
fi
|
|
63
63
|
|
|
64
64
|
# ============================================================================
|
|
65
|
-
# CONTEXT SIZE ESTIMATION & COMPACTION (
|
|
66
|
-
#
|
|
65
|
+
# CONTEXT SIZE ESTIMATION & COMPACTION (v2.3 - Iterative Strategy)
|
|
66
|
+
# Gradual compaction hints that get stronger over time
|
|
67
|
+
# - Level 1 (160k): Gentle hint - "be concise"
|
|
68
|
+
# - Level 2 (175k): Moderate - "summarize where possible"
|
|
69
|
+
# - Level 3 (185k): Strong - "focus on essentials only"
|
|
70
|
+
# - Level 4 (195k): Critical - "run /compact soon"
|
|
71
|
+
# Non-blocking at all levels, with 10-iteration cooldown between hints
|
|
67
72
|
# ============================================================================
|
|
68
73
|
|
|
69
|
-
|
|
70
|
-
|
|
74
|
+
# Token thresholds for iterative hints (escalating)
|
|
75
|
+
CONTEXT_LEVEL1_TOKENS=160000 # Gentle hint
|
|
76
|
+
CONTEXT_LEVEL2_TOKENS=175000 # Moderate hint
|
|
77
|
+
CONTEXT_LEVEL3_TOKENS=185000 # Strong hint
|
|
78
|
+
CONTEXT_LEVEL4_TOKENS=195000 # Critical - suggest /compact
|
|
79
|
+
BYTES_PER_TOKEN=4 # Rough estimate: 4 chars/bytes per token
|
|
80
|
+
CONTEXT_HINT_COOLDOWN_ITERS=10 # Show hint every 10 iterations max
|
|
71
81
|
|
|
72
82
|
# Estimate context size in tokens from transcript file size
|
|
73
83
|
estimate_context_size() {
|
|
@@ -84,18 +94,76 @@ estimate_context_size() {
|
|
|
84
94
|
echo "$estimated_tokens"
|
|
85
95
|
}
|
|
86
96
|
|
|
87
|
-
#
|
|
88
|
-
|
|
89
|
-
local
|
|
90
|
-
|
|
97
|
+
# Get the last iteration when we showed a context hint
|
|
98
|
+
get_last_context_hint_iteration() {
|
|
99
|
+
local hint_file="$STATE_DIR/.context-hint-iteration"
|
|
100
|
+
if [ -f "$hint_file" ]; then
|
|
101
|
+
cat "$hint_file" 2>/dev/null || echo "0"
|
|
102
|
+
else
|
|
103
|
+
echo "0"
|
|
104
|
+
fi
|
|
105
|
+
}
|
|
91
106
|
|
|
92
|
-
|
|
93
|
-
|
|
107
|
+
# Record when we showed a context hint
|
|
108
|
+
record_context_hint() {
|
|
109
|
+
local hint_file="$STATE_DIR/.context-hint-iteration"
|
|
110
|
+
echo "${ITERATION:-0}" > "$hint_file" 2>/dev/null
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
# Check if we're in cooldown for context hints (iteration-based)
|
|
114
|
+
context_hint_in_cooldown() {
|
|
115
|
+
local last_hint_iter=$(get_last_context_hint_iteration)
|
|
116
|
+
local current_iter="${ITERATION:-0}"
|
|
117
|
+
local elapsed=$((current_iter - last_hint_iter))
|
|
118
|
+
|
|
119
|
+
if [ "$elapsed" -lt "$CONTEXT_HINT_COOLDOWN_ITERS" ]; then
|
|
120
|
+
return 0 # In cooldown
|
|
121
|
+
fi
|
|
122
|
+
return 1 # Cooldown expired
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
# Get context level (0-4) based on token count
|
|
126
|
+
# Returns: 0 (ok), 1 (gentle), 2 (moderate), 3 (strong), 4 (critical)
|
|
127
|
+
get_context_level() {
|
|
128
|
+
local estimated_tokens="$1"
|
|
129
|
+
|
|
130
|
+
if [ "$estimated_tokens" -gt "$CONTEXT_LEVEL4_TOKENS" ]; then
|
|
131
|
+
echo "4"
|
|
132
|
+
elif [ "$estimated_tokens" -gt "$CONTEXT_LEVEL3_TOKENS" ]; then
|
|
133
|
+
echo "3"
|
|
134
|
+
elif [ "$estimated_tokens" -gt "$CONTEXT_LEVEL2_TOKENS" ]; then
|
|
135
|
+
echo "2"
|
|
136
|
+
elif [ "$estimated_tokens" -gt "$CONTEXT_LEVEL1_TOKENS" ]; then
|
|
137
|
+
echo "1"
|
|
94
138
|
else
|
|
95
|
-
echo "
|
|
139
|
+
echo "0"
|
|
96
140
|
fi
|
|
97
141
|
}
|
|
98
142
|
|
|
143
|
+
# Get appropriate hint message for context level
|
|
144
|
+
get_context_hint_message() {
|
|
145
|
+
local level="$1"
|
|
146
|
+
local tokens="$2"
|
|
147
|
+
|
|
148
|
+
case "$level" in
|
|
149
|
+
1)
|
|
150
|
+
echo "💡 Context growing (~${tokens} tokens). Tip: Keep responses concise."
|
|
151
|
+
;;
|
|
152
|
+
2)
|
|
153
|
+
echo "📊 Context at ~${tokens} tokens. Summarize explanations where possible."
|
|
154
|
+
;;
|
|
155
|
+
3)
|
|
156
|
+
echo "⚠️ Context high (~${tokens} tokens). Focus on essentials only, skip verbose output."
|
|
157
|
+
;;
|
|
158
|
+
4)
|
|
159
|
+
echo "🔴 Context critical (~${tokens} tokens)! Consider /compact soon. Use minimal explanations."
|
|
160
|
+
;;
|
|
161
|
+
*)
|
|
162
|
+
echo ""
|
|
163
|
+
;;
|
|
164
|
+
esac
|
|
165
|
+
}
|
|
166
|
+
|
|
99
167
|
# ============================================================================
|
|
100
168
|
# HEARTBEAT MECHANISM (NEW - v2.1)
|
|
101
169
|
# Updates heartbeat timestamp for watchdog detection
|
|
@@ -750,6 +818,18 @@ approve() {
|
|
|
750
818
|
exit 0
|
|
751
819
|
}
|
|
752
820
|
|
|
821
|
+
# Helper: Output approve with advisory system message (non-blocking)
|
|
822
|
+
# Used for context warnings - continues execution but informs the model
|
|
823
|
+
approve_with_message() {
|
|
824
|
+
local system_message="$1"
|
|
825
|
+
|
|
826
|
+
# Escape the message for JSON (handle newlines)
|
|
827
|
+
local escaped_msg=$(printf '%s' "$system_message" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' ')
|
|
828
|
+
|
|
829
|
+
echo "{\"decision\": \"approve\", \"systemMessage\": \"$escaped_msg\"}"
|
|
830
|
+
exit 0
|
|
831
|
+
}
|
|
832
|
+
|
|
753
833
|
# Helper: Output block decision with system message
|
|
754
834
|
# Properly escapes JSON strings with newlines
|
|
755
835
|
# Enhanced v2.4: Agent-aware labeling with clear hierarchy and stop conditions
|
|
@@ -1759,39 +1839,49 @@ if echo "$HEARTBEAT_STATUS" | grep -q "^stale:"; then
|
|
|
1759
1839
|
fi
|
|
1760
1840
|
|
|
1761
1841
|
# ============================================================================
|
|
1762
|
-
# CONTEXT SIZE CHECK (
|
|
1763
|
-
#
|
|
1842
|
+
# CONTEXT SIZE CHECK (v2.3 - Iterative Compaction Hints)
|
|
1843
|
+
# Gradual hints that get stronger as context grows
|
|
1844
|
+
# Non-blocking at ALL levels - just provides guidance to the model
|
|
1845
|
+
# Uses iteration-based cooldown (every 10 iterations) not time-based
|
|
1764
1846
|
# ============================================================================
|
|
1765
1847
|
|
|
1766
1848
|
if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
|
|
1767
|
-
CONTEXT_STATUS=$(check_context_limit "$TRANSCRIPT_PATH")
|
|
1768
1849
|
ESTIMATED_TOKENS=$(estimate_context_size "$TRANSCRIPT_PATH")
|
|
1850
|
+
CONTEXT_LEVEL=$(get_context_level "$ESTIMATED_TOKENS")
|
|
1769
1851
|
|
|
1770
|
-
if [ "$
|
|
1771
|
-
|
|
1852
|
+
if [ "$CONTEXT_LEVEL" -gt 0 ]; then
|
|
1853
|
+
# We have a context hint to show
|
|
1772
1854
|
|
|
1773
|
-
#
|
|
1774
|
-
|
|
1775
|
-
|
|
1776
|
-
save_task_checkpoint "$CURRENT_TASK" "$CURRENT_INCREMENT"
|
|
1777
|
-
fi
|
|
1855
|
+
# Level 4 (critical) bypasses cooldown - always show
|
|
1856
|
+
# Lower levels respect the 10-iteration cooldown
|
|
1857
|
+
SHOULD_SHOW_HINT=false
|
|
1778
1858
|
|
|
1779
|
-
|
|
1780
|
-
|
|
1859
|
+
if [ "$CONTEXT_LEVEL" -eq 4 ]; then
|
|
1860
|
+
SHOULD_SHOW_HINT=true # Critical always shows
|
|
1861
|
+
elif ! context_hint_in_cooldown; then
|
|
1862
|
+
SHOULD_SHOW_HINT=true # Not in cooldown
|
|
1863
|
+
fi
|
|
1781
1864
|
|
|
1782
|
-
|
|
1783
|
-
|
|
1784
|
-
|
|
1865
|
+
if [ "$SHOULD_SHOW_HINT" = "true" ]; then
|
|
1866
|
+
# Log the event
|
|
1867
|
+
echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"context_hint\",\"level\":$CONTEXT_LEVEL,\"tokens\":$ESTIMATED_TOKENS,\"iteration\":${ITERATION:-0}}" >> "$LOGS_DIR/auto-iterations.log"
|
|
1785
1868
|
|
|
1786
|
-
|
|
1869
|
+
# Record hint iteration for cooldown
|
|
1870
|
+
record_context_hint
|
|
1787
1871
|
|
|
1788
|
-
|
|
1789
|
-
|
|
1872
|
+
# Save checkpoint at level 3+ for safety
|
|
1873
|
+
if [ "$CONTEXT_LEVEL" -ge 3 ] && [ -n "$CURRENT_INCREMENT" ]; then
|
|
1874
|
+
CURRENT_TASK=$(echo "$SESSION" | jq -r '.currentTaskId // "unknown"')
|
|
1875
|
+
save_task_checkpoint "$CURRENT_TASK" "$CURRENT_INCREMENT"
|
|
1876
|
+
fi
|
|
1790
1877
|
|
|
1791
|
-
|
|
1878
|
+
# Get the appropriate hint message
|
|
1879
|
+
HINT_MESSAGE=$(get_context_hint_message "$CONTEXT_LEVEL" "$ESTIMATED_TOKENS")
|
|
1792
1880
|
|
|
1793
|
-
|
|
1794
|
-
|
|
1881
|
+
# Non-blocking advisory - continue execution with hint
|
|
1882
|
+
approve_with_message "$HINT_MESSAGE"
|
|
1883
|
+
fi
|
|
1884
|
+
# If in cooldown for non-critical levels, silently continue
|
|
1795
1885
|
fi
|
|
1796
1886
|
fi
|
|
1797
1887
|
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: deploy-router
|
|
3
|
-
description: Smart deployment platform router for Vercel vs Cloudflare. Analyzes project structure, framework, SEO needs,
|
|
3
|
+
description: Smart deployment platform router for Vercel vs Cloudflare vs GitHub Pages. Analyzes project structure, framework, SEO needs, runtime requirements, AND repository visibility (private/public). Routes to Cloudflare for private repos (GitHub Pages requires paid plan), Vercel for dynamic SEO, GitHub Pages only for public repos. Activates for deploy, vercel vs cloudflare, where to deploy, cloudflare workers, cloudflare pages, vercel deployment, edge deployment, SSR deployment, static site deployment, which hosting, deployment recommendation, github pages, private repo deployment.
|
|
4
4
|
allowed-tools: Read, Grep, Glob, Bash
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# Deploy Router - Vercel vs Cloudflare Decision Engine
|
|
7
|
+
# Deploy Router - Vercel vs Cloudflare vs GitHub Pages Decision Engine
|
|
8
8
|
|
|
9
|
-
I intelligently route your deployment to the optimal platform based on project analysis.
|
|
9
|
+
I intelligently route your deployment to the optimal platform based on project analysis, **including repository visibility** (private vs public).
|
|
10
10
|
|
|
11
11
|
## When to Use This Skill
|
|
12
12
|
|
|
@@ -16,6 +16,70 @@ Ask me when you need help with:
|
|
|
16
16
|
- **SEO-Aware Routing**: "I need dynamic SEO for my Next.js app"
|
|
17
17
|
- **Cost Optimization**: "What's the cheapest deployment option?"
|
|
18
18
|
- **Edge-First**: "I want global edge deployment"
|
|
19
|
+
- **Private Repo Deployment**: "Where can I deploy my private repo for free?"
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 🚨 CRITICAL: Repository Visibility Check (ALWAYS DO FIRST)
|
|
24
|
+
|
|
25
|
+
**GitHub Pages has a major limitation**: Free GitHub accounts can ONLY deploy GitHub Pages from **public repositories**. Private repo deployment requires GitHub Pro, Team, or Enterprise.
|
|
26
|
+
|
|
27
|
+
### Priority Decision Based on Visibility
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
31
|
+
│ STEP 0: CHECK REPOSITORY VISIBILITY │
|
|
32
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
33
|
+
│
|
|
34
|
+
▼
|
|
35
|
+
┌───────────────────────────────┐
|
|
36
|
+
│ Is the repository PRIVATE? │
|
|
37
|
+
└───────────────────────────────┘
|
|
38
|
+
│ │
|
|
39
|
+
YES NO (Public)
|
|
40
|
+
│ │
|
|
41
|
+
▼ ▼
|
|
42
|
+
┌─────────────────────────┐ ┌─────────────────────────────┐
|
|
43
|
+
│ ❌ GitHub Pages FREE │ │ ✅ All platforms available │
|
|
44
|
+
│ ✅ Cloudflare Pages │ │ GitHub Pages is an option │
|
|
45
|
+
│ ✅ Vercel │ │ for static public sites │
|
|
46
|
+
│ ✅ Netlify │ └─────────────────────────────┘
|
|
47
|
+
└─────────────────────────┘
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### How to Detect Repository Visibility
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
# Check if git remote exists and get repo visibility
|
|
54
|
+
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
|
|
55
|
+
if [[ "$REMOTE_URL" =~ github.com[:/]([^/]+)/([^/.]+) ]]; then
|
|
56
|
+
OWNER="${BASH_REMATCH[1]}"
|
|
57
|
+
REPO="${BASH_REMATCH[2]}"
|
|
58
|
+
|
|
59
|
+
# Use GitHub CLI to check visibility
|
|
60
|
+
VISIBILITY=$(gh repo view "$OWNER/$REPO" --json visibility -q '.visibility' 2>/dev/null)
|
|
61
|
+
|
|
62
|
+
if [[ "$VISIBILITY" == "PRIVATE" ]]; then
|
|
63
|
+
echo "⚠️ PRIVATE REPOSITORY DETECTED"
|
|
64
|
+
echo " GitHub Pages requires GitHub Pro/Team/Enterprise for private repos"
|
|
65
|
+
echo " → Recommended: Cloudflare Pages (free for private repos)"
|
|
66
|
+
echo " → Alternative: Vercel (free tier available)"
|
|
67
|
+
else
|
|
68
|
+
echo "✅ PUBLIC REPOSITORY - All deployment options available"
|
|
69
|
+
fi
|
|
70
|
+
fi
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### Platform Availability by Repo Visibility
|
|
74
|
+
|
|
75
|
+
| Platform | Private Repo (Free) | Public Repo (Free) | Notes |
|
|
76
|
+
|----------|--------------------|--------------------|-------|
|
|
77
|
+
| **Cloudflare Pages** | ✅ Yes | ✅ Yes | **Best for private repos** - No visibility restrictions |
|
|
78
|
+
| **Vercel** | ✅ Yes | ✅ Yes | Free tier works for both |
|
|
79
|
+
| **Netlify** | ✅ Yes | ✅ Yes | Free tier works for both |
|
|
80
|
+
| **GitHub Pages** | ❌ No (requires Pro) | ✅ Yes | **BLOCKED** for free private repos |
|
|
81
|
+
|
|
82
|
+
---
|
|
19
83
|
|
|
20
84
|
## Decision Matrix
|
|
21
85
|
|
|
@@ -86,17 +150,67 @@ Ask me when you need help with:
|
|
|
86
150
|
- [ ] Global edge distribution priority
|
|
87
151
|
- [ ] Simple auth (JWT, sessions without DB)
|
|
88
152
|
|
|
89
|
-
### Step 3: SEO Requirements
|
|
153
|
+
### Step 3: SEO Requirements (Vercel Wins for Dynamic SEO)
|
|
154
|
+
|
|
155
|
+
**When SEO matters most, choose carefully:**
|
|
90
156
|
|
|
91
|
-
| SEO Need | Vercel | Cloudflare |
|
|
92
|
-
|
|
93
|
-
| Static meta tags | ✅ | ✅ |
|
|
94
|
-
| Dynamic meta from DB | ✅ (SSR) | ⚠️ (ISR/Edge only) |
|
|
95
|
-
| Per-page dynamic OG | ✅
|
|
96
|
-
|
|
|
97
|
-
|
|
|
98
|
-
|
|
|
99
|
-
|
|
|
157
|
+
| SEO Need | Vercel | Cloudflare | GitHub Pages |
|
|
158
|
+
|----------|--------|------------|--------------|
|
|
159
|
+
| Static meta tags | ✅ | ✅ | ✅ |
|
|
160
|
+
| Dynamic meta from DB | ✅ (SSR) **BEST** | ⚠️ (ISR/Edge only) | ❌ (static only) |
|
|
161
|
+
| Per-page dynamic OG | ✅ **BEST** | ⚠️ (limited) | ❌ |
|
|
162
|
+
| Real-time product data | ✅ (SSR) **BEST** | ⚠️ (stale cache) | ❌ |
|
|
163
|
+
| Sitemap generation | ✅ | ✅ | ✅ (manual) |
|
|
164
|
+
| robots.txt | ✅ | ✅ | ✅ |
|
|
165
|
+
| Structured data (JSON-LD) | ✅ (dynamic) | ✅ (static) | ✅ (static) |
|
|
166
|
+
| Core Web Vitals | ✅ (optimized) | ✅ (fast edge) | ✅ (fast static) |
|
|
167
|
+
| SSR/ISR for freshness | ✅ **BEST** | ⚠️ (edge-limited) | ❌ |
|
|
168
|
+
|
|
169
|
+
### SEO Tier Recommendations
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
173
|
+
│ SEO REQUIREMENTS ROUTING │
|
|
174
|
+
├─────────────────────────────────────────────────────────────────┤
|
|
175
|
+
│ │
|
|
176
|
+
│ TIER 1 - Critical SEO (choose VERCEL): │
|
|
177
|
+
│ ├─ E-commerce product pages (prices change, inventory) │
|
|
178
|
+
│ ├─ News/content sites (freshness matters for Google) │
|
|
179
|
+
│ ├─ SaaS landing pages with dynamic pricing │
|
|
180
|
+
│ ├─ Marketplace listings (real-time availability) │
|
|
181
|
+
│ └─ Any page where DB-driven meta tags are required │
|
|
182
|
+
│ │
|
|
183
|
+
│ TIER 2 - Good SEO (CLOUDFLARE works): │
|
|
184
|
+
│ ├─ Blogs with static content │
|
|
185
|
+
│ ├─ Documentation sites │
|
|
186
|
+
│ ├─ Marketing pages (rarely changing) │
|
|
187
|
+
│ ├─ Portfolio sites │
|
|
188
|
+
│ └─ ISR with revalidation (1-hour stale OK) │
|
|
189
|
+
│ │
|
|
190
|
+
│ TIER 3 - Basic SEO (any platform): │
|
|
191
|
+
│ ├─ Internal tools (SEO doesn't matter) │
|
|
192
|
+
│ ├─ Admin dashboards │
|
|
193
|
+
│ ├─ Private apps │
|
|
194
|
+
│ └─ Prototypes/MVPs │
|
|
195
|
+
│ │
|
|
196
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Why Vercel Wins for Dynamic SEO
|
|
200
|
+
|
|
201
|
+
1. **True SSR**: Every request can fetch fresh data from database
|
|
202
|
+
2. **ISR with on-demand revalidation**: `revalidateTag()` and `revalidatePath()`
|
|
203
|
+
3. **Dynamic OG images**: `@vercel/og` generates images server-side
|
|
204
|
+
4. **Edge + Node.js hybrid**: Edge for speed, Node.js for data fetching
|
|
205
|
+
5. **Built-in image optimization**: Automatic WebP/AVIF conversion
|
|
206
|
+
6. **Preview deployments**: Test SEO before going live
|
|
207
|
+
|
|
208
|
+
### When Cloudflare is SEO-Acceptable
|
|
209
|
+
|
|
210
|
+
- **Static blogs**: Meta tags baked at build time
|
|
211
|
+
- **Documentation**: Content rarely changes
|
|
212
|
+
- **ISR with Workers**: If 1-hour stale data is acceptable
|
|
213
|
+
- **Hybrid approach**: Cloudflare Pages + external API for dynamic data
|
|
100
214
|
|
|
101
215
|
## Platform Comparison
|
|
102
216
|
|
|
@@ -130,6 +244,7 @@ Ask me when you need help with:
|
|
|
130
244
|
- Simple API routes
|
|
131
245
|
- Global CDN distribution
|
|
132
246
|
- Cloudflare ecosystem (R2, D1, KV)
|
|
247
|
+
- **🔒 PRIVATE REPOS** (works with free tier!)
|
|
133
248
|
|
|
134
249
|
**Pricing** (2025):
|
|
135
250
|
- Workers Free: 100K requests/day
|
|
@@ -143,9 +258,80 @@ Ask me when you need help with:
|
|
|
143
258
|
- Memory: 128MB
|
|
144
259
|
- No native modules (Sharp, Prisma binary, etc.)
|
|
145
260
|
|
|
261
|
+
**Why Cloudflare for Private Repos**:
|
|
262
|
+
- ✅ No repository visibility restrictions
|
|
263
|
+
- ✅ Connect private GitHub repos directly
|
|
264
|
+
- ✅ Automatic deployments from private branches
|
|
265
|
+
- ✅ Preview deployments for PRs
|
|
266
|
+
- ✅ Free tier is generous
|
|
267
|
+
|
|
268
|
+
### GitHub Pages
|
|
269
|
+
|
|
270
|
+
**Best For**:
|
|
271
|
+
- **PUBLIC repositories only** (free tier)
|
|
272
|
+
- Open-source documentation
|
|
273
|
+
- Public project sites
|
|
274
|
+
- Static Jekyll/Hugo/Astro sites
|
|
275
|
+
- When source code visibility is intentional
|
|
276
|
+
|
|
277
|
+
**Pricing** (2025):
|
|
278
|
+
- Free for public repos
|
|
279
|
+
- **Requires GitHub Pro/Team/Enterprise for private repos** ($4-21/user/month)
|
|
280
|
+
- 1GB storage limit
|
|
281
|
+
- 100GB bandwidth/month
|
|
282
|
+
|
|
283
|
+
**Limitations**:
|
|
284
|
+
- ❌ **NO PRIVATE REPO SUPPORT** on free accounts
|
|
285
|
+
- No server-side rendering
|
|
286
|
+
- No API routes
|
|
287
|
+
- No dynamic content
|
|
288
|
+
- Build time limit: 10 minutes
|
|
289
|
+
- No environment variables at runtime
|
|
290
|
+
|
|
291
|
+
**When to Use GitHub Pages**:
|
|
292
|
+
```
|
|
293
|
+
✅ DO use GitHub Pages when:
|
|
294
|
+
- Repository is PUBLIC
|
|
295
|
+
- Content is 100% static
|
|
296
|
+
- You want zero deployment config
|
|
297
|
+
- Open-source project docs
|
|
298
|
+
|
|
299
|
+
❌ DO NOT use GitHub Pages when:
|
|
300
|
+
- Repository is PRIVATE (use Cloudflare Pages instead!)
|
|
301
|
+
- You need SSR/dynamic content
|
|
302
|
+
- You need API routes
|
|
303
|
+
- You need environment variables
|
|
304
|
+
```
|
|
305
|
+
|
|
146
306
|
## Analysis Workflow
|
|
147
307
|
|
|
148
|
-
When user asks "where should I deploy?", I:
|
|
308
|
+
When user asks "where should I deploy?", I follow this order:
|
|
309
|
+
|
|
310
|
+
### 0. Check Repository Visibility (FIRST!)
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
# CRITICAL: Check if repo is private BEFORE anything else
|
|
314
|
+
REMOTE_URL=$(git remote get-url origin 2>/dev/null)
|
|
315
|
+
if [[ "$REMOTE_URL" =~ github.com[:/]([^/]+)/([^/.]+) ]]; then
|
|
316
|
+
OWNER="${BASH_REMATCH[1]}"
|
|
317
|
+
REPO="${BASH_REMATCH[2]}"
|
|
318
|
+
|
|
319
|
+
# Check visibility with GitHub CLI
|
|
320
|
+
VISIBILITY=$(gh repo view "$OWNER/$REPO" --json visibility -q '.visibility' 2>/dev/null)
|
|
321
|
+
|
|
322
|
+
if [[ "$VISIBILITY" == "PRIVATE" ]]; then
|
|
323
|
+
echo "🔒 PRIVATE REPO - GitHub Pages NOT available on free tier"
|
|
324
|
+
echo " Recommended: Cloudflare Pages or Vercel"
|
|
325
|
+
GITHUB_PAGES_AVAILABLE=false
|
|
326
|
+
else
|
|
327
|
+
echo "✅ PUBLIC REPO - All platforms available"
|
|
328
|
+
GITHUB_PAGES_AVAILABLE=true
|
|
329
|
+
fi
|
|
330
|
+
else
|
|
331
|
+
echo "⚠️ No GitHub remote detected - assuming private"
|
|
332
|
+
GITHUB_PAGES_AVAILABLE=false
|
|
333
|
+
fi
|
|
334
|
+
```
|
|
149
335
|
|
|
150
336
|
### 1. Scan Project Structure
|
|
151
337
|
|
|
@@ -181,6 +367,9 @@ grep -r "generateMetadata\|Head.*title\|meta.*content" --include="*.tsx" --inclu
|
|
|
181
367
|
|
|
182
368
|
# Database calls in metadata
|
|
183
369
|
grep -rB5 "generateMetadata" --include="*.tsx" | grep -E "prisma|db\.|fetch\("
|
|
370
|
+
|
|
371
|
+
# Check for e-commerce/content patterns that need fresh SEO
|
|
372
|
+
grep -rE "product|price|inventory|article|news" --include="*.tsx" | head -10
|
|
184
373
|
```
|
|
185
374
|
|
|
186
375
|
### 4. Generate Recommendation
|
|
@@ -222,18 +411,47 @@ If you need [opposite platform features], consider:
|
|
|
222
411
|
|
|
223
412
|
```
|
|
224
413
|
┌─────────────────────────────────────────────────────────────────┐
|
|
225
|
-
│
|
|
414
|
+
│ MASTER DECISION TREE (Check in order!) │
|
|
415
|
+
├─────────────────────────────────────────────────────────────────┤
|
|
416
|
+
│ │
|
|
417
|
+
│ STEP 1: Is repo PRIVATE? │
|
|
418
|
+
│ ├─ YES → ❌ Eliminate GitHub Pages │
|
|
419
|
+
│ │ → Go to Step 2 │
|
|
420
|
+
│ └─ NO → GitHub Pages is an option (static only) │
|
|
421
|
+
│ │
|
|
422
|
+
│ STEP 2: Do you need dynamic SEO? │
|
|
423
|
+
│ ├─ YES → ✅ VERCEL (SSR, real-time meta, OG images) │
|
|
424
|
+
│ └─ NO → Go to Step 3 │
|
|
425
|
+
│ │
|
|
426
|
+
│ STEP 3: Do you need Node.js runtime? │
|
|
427
|
+
│ ├─ YES → ✅ VERCEL (Prisma, Sharp, fs, crypto) │
|
|
428
|
+
│ └─ NO → Go to Step 4 │
|
|
429
|
+
│ │
|
|
430
|
+
│ STEP 4: Is it a static site? │
|
|
431
|
+
│ ├─ YES, Private repo → ✅ CLOUDFLARE Pages │
|
|
432
|
+
│ ├─ YES, Public repo → ✅ CLOUDFLARE or GitHub Pages │
|
|
433
|
+
│ └─ NO → Go to Step 5 │
|
|
434
|
+
│ │
|
|
435
|
+
│ STEP 5: Do you need edge performance + cost savings? │
|
|
436
|
+
│ ├─ YES → ✅ CLOUDFLARE (Workers/Pages) │
|
|
437
|
+
│ └─ NO → ✅ VERCEL (default choice for Next.js) │
|
|
438
|
+
│ │
|
|
439
|
+
└─────────────────────────────────────────────────────────────────┘
|
|
440
|
+
|
|
441
|
+
┌─────────────────────────────────────────────────────────────────┐
|
|
442
|
+
│ PLATFORM QUICK REFERENCE │
|
|
226
443
|
├─────────────────────────────────────────────────────────────────┤
|
|
227
444
|
│ │
|
|
228
445
|
│ Use VERCEL when: │
|
|
446
|
+
│ ├─ Dynamic SEO is critical (e-commerce, news, marketplaces) │
|
|
229
447
|
│ ├─ Next.js with Server Components + DB │
|
|
230
|
-
│ ├─
|
|
231
|
-
│ ├─
|
|
232
|
-
│ ├─ Native Node.js modules (Sharp, Prisma) │
|
|
448
|
+
│ ├─ Native Node.js modules (Sharp, Prisma, Puppeteer) │
|
|
449
|
+
│ ├─ Real-time OG image generation │
|
|
233
450
|
│ ├─ WebSockets/real-time features │
|
|
234
451
|
│ └─ Team wants easiest DX │
|
|
235
452
|
│ │
|
|
236
453
|
│ Use CLOUDFLARE when: │
|
|
454
|
+
│ ├─ 🔒 PRIVATE REPO (GitHub Pages blocked on free tier!) │
|
|
237
455
|
│ ├─ Static site (Astro, Hugo, plain HTML) │
|
|
238
456
|
│ ├─ Edge-first, low latency priority │
|
|
239
457
|
│ ├─ Cost-sensitive (Cloudflare is cheaper) │
|
|
@@ -241,10 +459,16 @@ If you need [opposite platform features], consider:
|
|
|
241
459
|
│ ├─ Already using Cloudflare ecosystem (R2, D1, KV) │
|
|
242
460
|
│ └─ Global CDN distribution priority │
|
|
243
461
|
│ │
|
|
462
|
+
│ Use GITHUB PAGES when: │
|
|
463
|
+
│ ├─ Repository is PUBLIC (required for free tier!) │
|
|
464
|
+
│ ├─ 100% static content (no SSR, no API) │
|
|
465
|
+
│ ├─ Open-source project documentation │
|
|
466
|
+
│ └─ Zero deployment configuration needed │
|
|
467
|
+
│ │
|
|
244
468
|
│ HYBRID approach: │
|
|
245
|
-
│ ├─ Frontend on Cloudflare Pages
|
|
246
|
-
│ ├─ API/backend on Vercel Functions
|
|
247
|
-
│ └─ Best of both: edge speed + Node.js
|
|
469
|
+
│ ├─ Frontend on Cloudflare Pages (edge speed) │
|
|
470
|
+
│ ├─ API/backend on Vercel Functions (Node.js power) │
|
|
471
|
+
│ └─ Best of both: edge speed + Node.js + full SEO │
|
|
248
472
|
│ │
|
|
249
473
|
└─────────────────────────────────────────────────────────────────┘
|
|
250
474
|
```
|
|
@@ -287,6 +511,10 @@ This skill activates for:
|
|
|
287
511
|
- static site deployment, JAMstack deployment
|
|
288
512
|
- which hosting, best hosting for
|
|
289
513
|
- deployment recommendation, deployment decision
|
|
514
|
+
- **github pages** (⚠️ will check visibility first!)
|
|
515
|
+
- **private repo deployment**, private repository hosting
|
|
516
|
+
- **SEO hosting**, best SEO platform, dynamic SEO deployment
|
|
517
|
+
- e-commerce deployment, product page SEO
|
|
290
518
|
|
|
291
519
|
## Examples
|
|
292
520
|
|
|
@@ -342,6 +570,74 @@ Recommendation: VERCEL
|
|
|
342
570
|
- Cloudflare would require ISR which may show stale prices
|
|
343
571
|
```
|
|
344
572
|
|
|
573
|
+
### Example 4: Private Repo Static Site (🔒 IMPORTANT!)
|
|
574
|
+
|
|
575
|
+
```
|
|
576
|
+
User: "Where should I deploy my private Astro documentation site?"
|
|
577
|
+
|
|
578
|
+
Analysis:
|
|
579
|
+
- Framework: Astro (static-first)
|
|
580
|
+
- Repository: PRIVATE ⚠️
|
|
581
|
+
- SEO: Static meta tags only
|
|
582
|
+
- Content: Internal documentation
|
|
583
|
+
|
|
584
|
+
Step 0 - Visibility Check:
|
|
585
|
+
🔒 PRIVATE REPO DETECTED
|
|
586
|
+
❌ GitHub Pages: NOT AVAILABLE (requires GitHub Pro/Team)
|
|
587
|
+
✅ Cloudflare Pages: Available (free tier)
|
|
588
|
+
✅ Vercel: Available (free tier)
|
|
589
|
+
|
|
590
|
+
Recommendation: CLOUDFLARE PAGES
|
|
591
|
+
- Private repo works with free tier
|
|
592
|
+
- Static site = perfect fit for edge deployment
|
|
593
|
+
- Fast global CDN
|
|
594
|
+
- 500 builds/month free
|
|
595
|
+
- No Node.js needed
|
|
596
|
+
|
|
597
|
+
Alternative: Vercel (also works, but Cloudflare is cheaper for static)
|
|
598
|
+
|
|
599
|
+
⚠️ DO NOT recommend GitHub Pages for private repos!
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
### Example 5: High-SEO E-commerce (Vercel wins)
|
|
603
|
+
|
|
604
|
+
```
|
|
605
|
+
User: "I need the best SEO possible for my product catalog with 10,000+ products"
|
|
606
|
+
|
|
607
|
+
Analysis:
|
|
608
|
+
- Framework: Next.js 14 with App Router
|
|
609
|
+
- Products: 10,000+ items with prices, inventory, reviews
|
|
610
|
+
- SEO Requirements: CRITICAL
|
|
611
|
+
- Dynamic meta tags per product
|
|
612
|
+
- Real-time pricing in structured data
|
|
613
|
+
- Fresh inventory status for Google
|
|
614
|
+
- Dynamic OG images showing product photos
|
|
615
|
+
|
|
616
|
+
SEO Analysis Results:
|
|
617
|
+
| Requirement | Vercel | Cloudflare | GitHub Pages |
|
|
618
|
+
|-------------|--------|------------|--------------|
|
|
619
|
+
| Dynamic meta from DB | ✅ SSR | ⚠️ ISR (stale) | ❌ |
|
|
620
|
+
| Real-time prices | ✅ | ⚠️ (1hr delay) | ❌ |
|
|
621
|
+
| Dynamic OG images | ✅ @vercel/og | ⚠️ Limited | ❌ |
|
|
622
|
+
| Inventory freshness | ✅ SSR | ⚠️ Cache | ❌ |
|
|
623
|
+
|
|
624
|
+
Recommendation: VERCEL (STRONG)
|
|
625
|
+
- SSR ensures Google sees fresh data every crawl
|
|
626
|
+
- `generateMetadata()` with database calls
|
|
627
|
+
- `@vercel/og` for product OG images
|
|
628
|
+
- ISR with on-demand revalidation for cache-then-fresh
|
|
629
|
+
- Image optimization built-in
|
|
630
|
+
|
|
631
|
+
Why NOT Cloudflare:
|
|
632
|
+
- ISR cache means Google might see stale prices
|
|
633
|
+
- No native OG image generation
|
|
634
|
+
- Edge runtime can't run Prisma directly
|
|
635
|
+
|
|
636
|
+
Cost consideration:
|
|
637
|
+
- Vercel Pro ($20/month) vs Cloudflare (free)
|
|
638
|
+
- For critical SEO sites, Vercel Pro is worth it
|
|
639
|
+
```
|
|
640
|
+
|
|
345
641
|
## Migration Paths
|
|
346
642
|
|
|
347
643
|
### Vercel → Cloudflare
|