shiply-cli 0.26.1 → 0.27.0

package/dist/index.js

@@ -4,9 +4,10 @@ import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import { rm } from 'node:fs/promises';
+import { readdir, rm, stat } from 'node:fs/promises';
 import { confetti, shouldCelebrate } from './confetti.js';
 import { runDetect } from './detect.js';
+import { printPreflight, runNextPreflight } from './preflight.js';
 import { resolvePayloadDir } from './framework.js';
 import { detectSsr } from './ssr-adapters.js';
 import { prepareBundle } from './bundle.js';
@@ -290,6 +291,17 @@ async function main() {
             if (!dir)
                 throw new Error(`usage: shiply ${cmd} <dir>`);
             const apiKey = values.anonymous ? undefined : (values.key ?? (await loadApiKey()));
+            // Preflight (Next.js source dirs): catch wrong-shaped builds BEFORE they
+            // ship broken — Turbopack bundles, Vercel-shaped crons, publishing raw
+            // source with no worker build. Auto-fixes what's safe, instructs on the
+            // rest, and blocks only on fatals. Skipped with --no-ssr (static intent).
+            if (!values['no-ssr'] && !values.framework) {
+                const findings = await runNextPreflight(dir);
+                if (printPreflight(findings)) {
+                    process.exitCode = 1;
+                    return;
+                }
+            }
             // SSR / worker-bundle lane: a built Cloudflare-adapter project (SvelteKit,
             // Astro) or a wrangler worker (Hono/raw fetch) ships as a worker bundle.
             // Skipped when --no-ssr or --framework (static override) is passed.
@@ -311,6 +323,35 @@ async function main() {
                 publishDir = stagingDir;
                 spa = false; // SSR: an asset miss must 404 so the worker handles the route
                 stateDir = dir; // persist .shiply.json in the SOURCE dir, not the temp dir
+                // Bundle budget: warn while it's still cheap to fix. CF's cap is
+                // ~10MB gzipped; JS gzips ~4:1, so raw >30MB is the danger zone —
+                // name the biggest modules instead of describing them generically.
+                if (!bareJsonFlag) {
+                    try {
+                        const bundleDir = join(publishDir, '.shiply', 'bundle');
+                        const sizes = [];
+                        const walk = async (d, prefix) => {
+                            for (const ent of await readdir(d, { withFileTypes: true })) {
+                                const p = join(d, ent.name);
+                                if (ent.isDirectory())
+                                    await walk(p, `${prefix}${ent.name}/`);
+                                else
+                                    sizes.push({ name: `${prefix}${ent.name}`, bytes: (await stat(p)).size });
+                            }
+                        };
+                        await walk(bundleDir, '');
+                        const total = sizes.reduce((s, f) => s + f.bytes, 0);
+                        if (total > 30_000_000) {
+                            const top = sizes.sort((a, b) => b.bytes - a.bytes).slice(0, 3);
+                            console.log(`⚠ worker bundle is ${(total / 1e6).toFixed(1)}MB raw — approaching Cloudflare's ~10MB gzipped cap.\n` +
+                                `  largest modules: ${top.map((t) => `${t.name} ${(t.bytes / 1e6).toFixed(1)}MB`).join(', ')}\n` +
+                                `  dev/test routes usually shouldn't ship; remove them or lazy-import heavy deps.`);
+                        }
+                    }
+                    catch {
+                        /* budget check is best-effort */
+                    }
+                }
                 if (!bareJsonFlag) {
                     console.log(`✔ ${ssr.framework} (SSR) detected — deploying worker bundle`);
                     if (isr && isr.timeBased > 0) {
@@ -420,8 +461,21 @@ async function main() {
                 // its worker, so surface the server's errors instead of swallowing them.
                 if (res.function?.errors?.length) {
                     console.error(`\n✖ function deploy FAILED — the site's worker is NOT live:`);
-                    for (const err of res.function.errors)
-                        console.error(`    ${err}`);
+                    // Prefer the structured what/why/fix when the server sent it — the
+                    // fix line is imperative on purpose (agents execute it verbatim).
+                    if (res.function.errorsDetail?.length) {
+                        for (const d of res.function.errorsDetail) {
+                            console.error(`    ${d.what}${d.why ? ` — ${d.why}` : ''}`);
+                            if (d.fix)
+                                console.error(`    fix: ${d.fix}`);
+                            if (d.docs)
+                                console.error(`    docs: ${d.docs}`);
+                        }
+                    }
+                    else {
+                        for (const err of res.function.errors)
+                            console.error(`    ${err}`);
+                    }
                     // A worker source was present but did not deploy: the site is not what
                     // the user shipped, so exit non-zero. Static files DID go live, hence
                     // we still print the URL below — but automation/CI must see the failure.
@@ -433,6 +487,21 @@ async function main() {
                 }
                 for (const hint of res.function?.hints ?? [])
                     console.log(`    ${hint}`);
+                // Postflight: the server probed the live site right after the deploy.
+                // Not-ok means "deployed but broken at runtime" — print the actual
+                // runtime exception it pulled from the worker's logs (the user can't
+                // see it any other way) and fail loudly for automation.
+                const smoke = res.function?.smoke;
+                if (smoke && !smoke.ok) {
+                    console.error(`\n✖ deployed, but the site is NOT serving (HTTP ${smoke.status} at ${smoke.url})`);
+                    if (smoke.note)
+                        console.error(`    ${smoke.note}`);
+                    for (const line of smoke.runtimeErrors ?? [])
+                        console.error(`    runtime error: ${line}`);
+                    for (const hint of smoke.hints ?? [])
+                        console.error(`    fix: ${hint}`);
+                    process.exitCode = 1;
+                }
                 console.log(`\n  ${res.siteUrl}\n`);
                 // confirm the site actually serves, then celebrate
                 try {

package/dist/preflight.js

@@ -0,0 +1,152 @@
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+const exists = (p) => stat(p).then(() => true, () => false);
+const mtimeMs = (p) => stat(p).then((s) => s.mtimeMs, () => null);
+async function readJson(p) {
+    try {
+        return JSON.parse(await readFile(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function readNextConfig(dir) {
+    for (const f of ['next.config.ts', 'next.config.js', 'next.config.mjs']) {
+        try {
+            return await readFile(join(dir, f), 'utf8');
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+/** Major version out of a semver-ish range string ("^15.5.20" → 15). */
+const majorOf = (range) => {
+    const m = /(\d+)/.exec(range);
+    return m ? Number(m[1]) : null;
+};
+/** Run the Next.js preflight over a SOURCE directory. Returns [] for
+ *  non-Next dirs (cheap: one package.json read decides). */
+export async function runNextPreflight(dir) {
+    const pkgPath = join(dir, 'package.json');
+    const pkg = await readJson(pkgPath);
+    if (!pkg)
+        return [];
+    const deps = {
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+    };
+    if (!deps.next)
+        return [];
+    const findings = [];
+    const nextMajor = majorOf(deps.next);
+    const scripts = pkg.scripts ?? {};
+    const nextConfig = await readNextConfig(dir);
+    const isStaticExport = !!nextConfig && /output\s*:\s*['"]export['"]/.test(nextConfig);
+    // -- turbopack-build: OpenNext requires a webpack build. Auto-fix the build
+    //    script — this failure is otherwise silent-until-runtime.
+    const build = scripts.build ?? '';
+    if (!isStaticExport && /next\s+build/.test(build)) {
+        let fixedBuild = null;
+        if (/--turbopack\b/.test(build)) {
+            fixedBuild = build.replace(/\s*--turbopack\b/, nextMajor !== null && nextMajor >= 16 ? ' --webpack' : '');
+        }
+        else if (nextMajor !== null && nextMajor >= 16 && !/--webpack\b/.test(build)) {
+            fixedBuild = build.replace(/next\s+build/, 'next build --webpack');
+        }
+        if (fixedBuild !== null && fixedBuild !== build) {
+            const raw = await readFile(pkgPath, 'utf8');
+            // Surgical string replace preserves the user's package.json formatting.
+            const patched = raw.replace(JSON.stringify(build), JSON.stringify(fixedBuild));
+            if (patched !== raw) {
+                await writeFile(pkgPath, patched);
+                findings.push({
+                    id: 'turbopack-build',
+                    level: 'fixed',
+                    message: `package.json "build" changed to ${JSON.stringify(fixedBuild)} — OpenNext (Next-on-Cloudflare) requires a webpack build; Turbopack output silently doesn't work. Rebuild before publishing.`,
+                });
+            }
+            else {
+                findings.push({
+                    id: 'turbopack-build',
+                    level: 'fix',
+                    message: `your Next build must use webpack for Cloudflare — change the build script to ${JSON.stringify(fixedBuild)}, rebuild, then re-run shiply publish.`,
+                });
+            }
+        }
+    }
+    // -- static-export: output:'export' apps are STATIC sites — publish the
+    //    exported dir, don't take the worker-bundle lane.
+    if (isStaticExport) {
+        findings.push({
+            id: 'static-export',
+            level: 'note',
+            message: `next.config uses output:'export' — this is a static site. Run the build, then publish the exported out/ directory (shiply publish handles it as static; no worker needed).`,
+        });
+    }
+    // -- vercel-crons: translate vercel.json crons to .shiply/crons.json (same
+    //    {path,schedule} shape) so scheduled jobs keep firing after migration.
+    const vercel = await readJson(join(dir, 'vercel.json'));
+    const vercelCrons = vercel?.crons ?? [];
+    const shiplyCronsPath = join(dir, '.shiply', 'crons.json');
+    if (vercelCrons.length > 0 && !(await exists(shiplyCronsPath))) {
+        const crons = vercelCrons
+            .filter((c) => typeof c.path === 'string' && typeof c.schedule === 'string')
+            .map((c) => ({ path: c.path, schedule: c.schedule }));
+        if (crons.length > 0) {
+            await mkdir(join(dir, '.shiply'), { recursive: true });
+            await writeFile(shiplyCronsPath, `${JSON.stringify({ crons }, null, 2)}\n`);
+            findings.push({
+                id: 'vercel-crons',
+                level: 'fixed',
+                message: `translated ${crons.length} cron(s) from vercel.json to .shiply/crons.json — shiply reads the latter; without it your scheduled jobs silently stop after migrating.`,
+            });
+        }
+    }
+    // -- missing-build / stale-build-state: never publish raw Next SOURCE as a
+    //    static site (today's silent worst case), and warn when the app was
+    //    rebuilt but the worker bundle wasn't.
+    const workerBuilt = await mtimeMs(join(dir, '.open-next', 'worker.js'));
+    if (!isStaticExport) {
+        if (workerBuilt === null) {
+            findings.push({
+                id: 'missing-build',
+                level: 'fix',
+                fatal: true,
+                message: 'no Cloudflare worker build found (.open-next/worker.js). Build first: npx opennextjs-cloudflare build ' +
+                    '(requires a webpack next build — see any fixes above), then re-run shiply publish.',
+            });
+        }
+        else {
+            const appBuilt = await mtimeMs(join(dir, '.next', 'BUILD_ID'));
+            if (appBuilt !== null && appBuilt > workerBuilt + 60_000) {
+                findings.push({
+                    id: 'stale-build-state',
+                    level: 'warn',
+                    message: 'your .next build is newer than the worker bundle — you would publish STALE code. ' +
+                        'Re-bundle first: npx opennextjs-cloudflare build --skipNextBuild',
+                });
+            }
+        }
+    }
+    return findings;
+}
+/** Render the PREFLIGHT block to stderr (stable shape, greppable like
+ *  SITE_READY). Returns true when a fatal finding should block the publish. */
+export function printPreflight(findings) {
+    if (findings.length === 0)
+        return false;
+    const counts = { fixed: 0, fix: 0, warn: 0, note: 0 };
+    for (const f of findings)
+        counts[f.level]++;
+    const summary = Object.entries(counts)
+        .filter(([, n]) => n > 0)
+        .map(([k, n]) => `${n} ${k}`)
+        .join(', ');
+    process.stderr.write(`PREFLIGHT next.js — ${summary}\n`);
+    for (const f of findings) {
+        process.stderr.write(`  ${f.level.toUpperCase()} ${f.id}: ${f.message}\n`);
+    }
+    return findings.some((f) => f.fatal);
+}

package/dist/publish.js

@@ -92,21 +92,38 @@ export async function publish(dir, opts = {}) {
     // whole publish with "already finalized" even though the deploy succeeded.
     // Give it room, and treat that conflict as the success it is (an earlier
     // attempt completed after the client gave up on it).
-    // Say what's happening — finalize is one server-side call (file verification
-    // + worker deploy) and used to be a silent multi-minute gap for big bundles.
+    // The server streams NDJSON progress lines when asked (new servers), so a
+    // big-bundle finalize narrates its phases instead of being a silent
+    // multi-minute gap; old servers just return plain JSON and we print nothing.
     process.stderr.write('  ⋯ finalizing — server is verifying files and deploying the worker…\n');
     let finalized;
     try {
-        finalized = await api(created.upload.finalizeUrl, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ versionId: created.upload.versionId }),
-        }, { timeoutMs: 300_000 });
+        finalized = await finalizeWithProgress(created.upload.finalizeUrl, created.upload.versionId);
     }
     catch (e) {
         if (e instanceof ApiError && e.code === 'conflict' && /already finalized/.test(e.message)) {
             finalized = {}; // deployed by the earlier attempt; function info unavailable
         }
+        else if (!(e instanceof ApiError)) {
+            // Transport died mid-stream. Finalize replays idempotently server-side —
+            // one plain retry either returns the completed result or the
+            // 'already finalized' conflict (success) handled above.
+            try {
+                finalized = await api(created.upload.finalizeUrl, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ versionId: created.upload.versionId }),
+                }, { timeoutMs: 300_000 });
+            }
+            catch (e2) {
+                if (e2 instanceof ApiError && e2.code === 'conflict' && /already finalized/.test(e2.message)) {
+                    finalized = {};
+                }
+                else {
+                    throw e2;
+                }
+            }
+        }
         else {
             throw e;
         }
@@ -124,7 +141,94 @@ export async function publish(dir, opts = {}) {
         skipped: created.upload.skipped.length,
     };
 }
-const CONCURRENCY = 8;
+/** Server phase names → what the human/agent sees. `null` = internal detail,
+ *  don't print. Unknown phases print as-is so new server phases surface
+ *  without a CLI release. */
+const FINALIZE_PHASE_LABELS = {
+    lookup: 'checking version',
+    fileSelects: null,
+    headCopy: 'verifying files',
+    goLive: 'going live',
+    workerHook: null, // its sub-phases (loading/uploading/probing) stream individually
+};
+/** Finalize with live progress: sends `x-shiply-progress: stream` and renders
+ *  the server's NDJSON phase lines as they arrive; the final line carries the
+ *  result (or the error, mapped to ApiError exactly like api() would). Old
+ *  servers ignore the header and return plain JSON — handled transparently, so
+ *  new CLI ↔ old server keeps working. */
+async function finalizeWithProgress(url, versionId) {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), 300_000);
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-shiply-progress': 'stream' },
+            body: JSON.stringify({ versionId }),
+            signal: ac.signal,
+        });
+        const ctype = res.headers.get('content-type') ?? '';
+        if (!res.body || !ctype.includes('x-ndjson')) {
+            // Old server (or an error response): plain JSON, same as api().
+            const body = await res.json().catch(() => ({}));
+            if (!res.ok) {
+                const err = body.error;
+                throw new ApiError(err?.code ?? 'http_error', err?.message ?? `HTTP ${res.status}`, res.status);
+            }
+            return body;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        let final = null;
+        const handleLine = (line) => {
+            if (!line.trim())
+                return;
+            let obj;
+            try {
+                obj = JSON.parse(line);
+            }
+            catch {
+                return; // tolerate junk lines — the final {done} line is all we require
+            }
+            if (obj?.progress) {
+                const label = obj.progress in FINALIZE_PHASE_LABELS ? FINALIZE_PHASE_LABELS[obj.progress] : obj.progress;
+                if (label) {
+                    const secs = ((obj.ms ?? 0) / 1000).toFixed(1);
+                    process.stderr.write(`    · ${label}${obj.detail ? ` (${obj.detail})` : ''} — ${secs}s\n`);
+                }
+            }
+            else if (obj?.done) {
+                final = obj;
+            }
+        };
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let nl;
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                handleLine(buf.slice(0, nl));
+                buf = buf.slice(nl + 1);
+            }
+        }
+        handleLine(buf);
+        if (!final)
+            throw new Error('finalize stream ended without a result');
+        const outcome = final;
+        if (outcome.error) {
+            throw new ApiError(outcome.error.code ?? 'http_error', outcome.error.message ?? 'finalize failed', 500);
+        }
+        return outcome.result ?? {};
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// 16-way: uploads are small-object PUTs to one R2 origin — latency-bound, not
+// bandwidth-bound — and Node's fetch pool handles the fan-out fine. Roughly
+// halves the upload phase of a ~60-changed-file publish vs 8.
+const CONCURRENCY = 16;
 async function uploadAll(dir, targets) {
     let next = 0;
     const worker = async () => {

package/package.json

@@ -1,42 +1,42 @@
-{
-  "name": "shiply-cli",
-  "version": "0.26.1",
-  "description": "Publish static sites to shiply.now from the command line \u00e2\u20ac\u201d instant web hosting for agents.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "shiply": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "skill",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm build",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "shiply",
-    "hosting",
-    "static",
-    "deploy",
-    "agents",
-    "publish"
-  ],
-  "homepage": "https://shiply.now",
-  "devDependencies": {
-    "@types/node": "^22.15.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0"
-  },
-  "dependencies": {
-    "esbuild": "^0.25.12",
-    "smol-toml": "^1.7.0"
-  }
-}
+{
+  "name": "shiply-cli",
+  "version": "0.27.0",
+  "description": "Publish static sites to shiply.now from the command line \u00e2\u20ac\u201d instant web hosting for agents.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "shiply": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "shiply",
+    "hosting",
+    "static",
+    "deploy",
+    "agents",
+    "publish"
+  ],
+  "homepage": "https://shiply.now",
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.12",
+    "smol-toml": "^1.7.0"
+  }
+}

package/skill/SKILL.md

@@ -1,253 +1,253 @@
----
-name: shiply
-description: "shiply is the production backend for anything an agent builds — publish any app (static or full-stack SSR, any framework) and give it a live URL, custom domain, SQL database, server functions, email, and a marketplace to sell it. Use when the user asks to publish, host, deploy, share, or update a website/page/demo/report/app, or wants a live URL for generated files. Triggers - \"publish this\", \"host this\", \"put this online\", \"give me a link\", \"update the site\", \"deploy my SvelteKit/Astro/Next.js app\", shiply."
----
-
----
-
-> **IMPORTANT — npm package name is `shiply-cli`, NOT `shiply`.** A different
-> npm package named `shiply` (an auto-commit watcher) is published by someone
-> else — installing it does NOT give you the shiply.now CLI. Always use
-> `npx -y shiply-cli@latest …` or `npm install -g shiply-cli`. The CLI binary
-> on PATH is still named `shiply` once installed; the warning is only about
-> the npm package name.
-
-> **Skill freshness check.** Shiply ships new capabilities weekly.
-> **This skill: version 0.25.0, last updated 2026-07-08.**
-> To see what changed since your copy was written, fetch
-> `https://shiply.now/changelog.md` (date-grouped, newest first) — if it lists
-> capabilities newer than the date above, re-install with
-> `npx -y shiply-cli@latest skill --force` OR read the live copy at
-> `https://shiply.now/skill.md`.
-
----
-
-# shiply — the production backend for anything an agent builds
-
-**What it is.** Not static hosting. shiply takes whatever you build — a static page or a full-stack app in any framework — and gives it a live URL, a custom domain, a SQL database, server functions, email (send + receive), and a marketplace to sell it. One call. No account needed to start: anonymous sites are live immediately, last 24 hours, and can be claimed to keep.
-
-**Why use it.** Ship a complete, working product without stitching together a host + database + email + registrar + payments — it's one agent-native platform (MCP / CLI / REST parity). Hard-ceiling pricing ($0/$8/$24, plus a $49 Studio tier for client delivery — no usage meter on any tier), so a spike or DDoS can never become a surprise bill for the owner.
-
-**How (quickstart).** `shiply publish ./dir` (CLI) — or POST /api/v1/publish → PUT each file → POST finalize — returns a live URL + claimToken.
-
-**NEVER create a new site to update an existing one. Always re-publish to the
-same site** (same slug/claimToken) — otherwise you litter subdomains and lose
-the user's URL.
-
-**Re-publishing the same site is cheap — always prefer it over a new site.**
-Unchanged files are hash-skipped, and an unchanged SSR worker bundle skips
-redeploy entirely (fingerprinted against what's already live). A zero-change
-`shiply publish` on the same site completes in seconds, even for large SSR
-apps — so iterate freely by re-publishing, never by spinning up a fresh site.
-
-This file covers the core path: publish → authorize → update → claim → verify.
-Everything else (databases, domains, SSR, email, functions, client work) lives
-in the **topic files indexed at the bottom** — read the one that matches the
-task before improvising.
-
-## First publish on a new machine: ask for a permanent key in one step
-
-On a no-Bearer publish, include `"agentName": "<your-tool-name>"` in the body
-(e.g. `"Claude Code"`, `"Cursor"`). The response will include a `deviceAuth`
-object alongside the usual `claimUrl`:
-
-```
-"deviceAuth": {
-  "user_code": "ABCD-EFGH",
-  "device_code": "<long opaque token, keep private>",
-  "verification_url": "https://shiply.now/auth/ABCD-EFGH",
-  "poll_url": "https://shiply.now/api/v1/auth/device/poll",
-  "expires_in": 900,
-  "interval": 2
-}
-```
-
-Tell the user once, in plain language:
-
-> Your site is live at <siteUrl>. To keep it forever AND let me publish more
-> without re-pasting, open <verification_url> and click Allow.
-
-Then immediately poll `verification_url`'s sibling endpoint until the user
-acts:
-
-```
-POST https://shiply.now/api/v1/auth/device/poll
-{"device_code": "<the device_code from the response>"}
-```
-
-The response is one of `{status:"pending"}` (keep polling at `interval`s),
-`{status:"approved", api_key:"shp_...", slug_claimed:"..."}` (PERSIST the key —
-see "Save the key" below — the site is now permanent; Allow does both jobs in
-one click), `{status:"expired"|"denied"|"consumed"}` (stop). Cap your polling at
-the announced `expires_in` and respect `interval` — don't tight-loop.
-
-After approval, every future publish uses `Authorization: Bearer <api_key>`
-and the user's dashboard shows their sites without any further claiming.
-
-### Save the key — so EVERY future site is seamless (do this once)
-
-Write the key to **`~/.shiply/credentials`** as `{"apiKey":"shp_..."}` (chmod
-600) — the exact file the shiply CLI reads. This is what makes "one Allow, ever"
-work: from then on every publish (any site, any project, ANY FUTURE SESSION)
-sends `Authorization: Bearer <key>` automatically and lands owned in the user's
-dashboard — no re-authorizing, no claim step, zero clicks. An env var alone
-(`SHIPLY_API_KEY`) works for the current shell but does NOT survive a new
-session — the credentials file is what makes it permanent. `shiply login` writes
-this file for you; if you publish over raw HTTP, write it yourself.
-
-## When the user pastes you something shiply-shaped, do this
-
-These are the patterns you will see. Match the input, run the action — do not
-ask the user to repeat themselves or explain.
-
-- **Code like `SHIPLY-XXXXXXXX`** → it's a pairing code from
-  `shiply.now/claim/<slug>?pair=1`. The user wants to attach an anonymous
-  site to their account. Run `shiply claim verify SHIPLY-XXXXXXXX` from the
-  directory you originally published from (it reads `.shiply.json`). No CLI?
-  POST `https://shiply.now/api/v1/claim/pair/SHIPLY-XXXXXXXX/verify` with
-  `{"siteId":"...","claimToken":"..."}` taken from your earlier publish
-  response or `.shiply.json`. The user's browser auto-redirects on success;
-  tell them to switch back to it.
-- **URL like `https://shiply.now/claim/<slug>?token=...`** → one-click claim
-  link. Tell the user to open it in the browser they are signed in to —
-  do NOT call any API yourself.
-- **User says "claim my site" / "save it forever" with no code or URL** →
-  give them the `claimUrl` from your last publish response. If you no longer
-  have that response but `.shiply.json` is in the publish dir, reconstruct it
-  as `https://shiply.now/claim/<slug>?token=<claimToken>` from those fields.
-  Either way, also suggest `shiply login` so future publishes mint to their
-  account directly — that's the long-term fix and how the dashboard works.
-- **User says "I have an API key now, use it from now on"** → persist it to
-  `~/.shiply/credentials` (`{"apiKey":"shp_..."}`, chmod 600 — see "Save the
-  key" above), then send `Authorization: Bearer <key>` on every future publish.
-  All future sites are then permanent and appear in their dashboard
-  automatically — across sessions, with no re-authorizing.
-- **User opens an `https://shiply.now/auth/XXXX-YYYY` URL you printed** → no
-  action from you; they're on the device-flow consent screen. Keep polling
-  `poll_url` (see "First publish on a new machine" above). The poll response
-  will flip from `pending` to `approved` (with `api_key`) the moment they
-  click Allow.
-
-## Pick your interface (best first)
-
-### 1. MCP (native tools)
-If the `shiply` MCP server is connected (https://shiply.now/mcp), use
-`publish_site`. Every result includes a `toUpdate` field telling you the exact
-call for updates — follow it, and a `shareSuggestion` you can relay to the user.
-Core tools: `site_status`, `list_sites`, `get_site`, `delete_site`, `whoami`,
-`duplicate_site`, `set_variable`, `get_analytics`, `set_handle`. There are
-100+ tools in total — call `tools/list` for the authoritative set; the topic
-files below name the tools for their area (domains, databases, email,
-functions, projects, contracts, marketplace, drives).
-
-### 2. CLI
-```bash
-# IMPORTANT: the npm package is `shiply-cli`, not `shiply` (different package).
-npm i -g shiply-cli        # or: npx -y shiply-cli@latest <command>
-                           # or: curl -fsSL https://shiply.now/install.sh | bash
-shiply publish ./dir       # live URL + confetti
-shiply publish ./dir       # run AGAIN after edits → updates the SAME site
-shiply status <slug> --wait  # SSL + readiness; prints SSL_READY / SITE_READY
-shiply login               # email code → API key → sites become permanent
-shiply claim verify <code> # confirm a SHIPLY-XXXXXXXX pairing code from /claim/<slug>?pair=1
-                           # (uses .shiply.json from CWD; pairs agent session to user's browser)
-```
-The CLI stores each directory's site in `.shiply.json` (slug + update token),
-so repeat publishes reuse the URL automatically. `--new-site` opts out.
-Gitignore `.shiply.json` in public repos. Parse `SITE_READY` / `SSL_READY`
-lines for automation; exit code 0 = ready. For a static framework build
-(Vite, Next export, Hugo, …) publish the BUILD OUTPUT, not the source — run
-`shiply detect` to see what the CLI found; the full framework matrix is in
-[references/publishing.md](references/publishing.md).
-
-### 3. Raw HTTP (no installs)
-```
-1. POST https://shiply.now/api/v1/publish   (Content-Type: application/json)
-   {
-     "agentName": "<your tool name, e.g. Claude Code, Cursor, Codex>",
-     "files": [{"path":"index.html","size":<bytes>,"contentType":"text/html","hash":"<sha256 lowercase hex, optional>"}]
-   }
-   (+ "Authorization: Bearer shp_…" for permanent owned sites)
-2. PUT each file's bytes to response upload.uploads[].url
-3. POST upload.finalizeUrl with {"versionId":"<upload.versionId from step 1>"}
-   → both the publish and finalize responses include a "toUpdate" string: the
-     exact call to update THIS site next time. Follow it — never create a new one.
-```
-
-**ALWAYS include `agentName` on anonymous publishes.** The response then
-carries `deviceAuth` ({user_code, verification_url, poll_url, device_code,
-expires_in, interval}) alongside `claimUrl`. Show the user `verification_url`,
-poll `poll_url` every `interval` seconds with the `device_code`, and on
-`{status:"approved"}` you get a permanent `api_key` PLUS the linked site
-is claimed in the same Allow click. Without `agentName` the user has to
-do a separate manual claim step every time.
-
-**Updates (the response tells you how):** every publish/finalize response
-includes a `toUpdate` string with the exact call — follow it verbatim. In short:
-anonymous → include `"claimToken":"..."` (returned ONCE by the first publish —
-save it); owned → include `"slug":"..."`. Hashes make updates cheap: unchanged
-files are skipped server-side.
-
-## Verify before you say "done"
-
-`shiply status <slug> --wait` polls until the site serves (exit 0, prints
-`SITE_READY` / `SSL_READY`). `shiply verify <slug>` runs a deeper edge
-SSL + HTTP + thumbnail check and prints a stable machine marker line
-`VERIFY status=LIVE http=200 ssl=valid …` — parse that line in automation.
-More manage commands (list, delete, rollback, promote, stable previews) are
-in [references/publishing.md](references/publishing.md).
-
-## The lifecycle to explain to users
-- Anonymous site: live immediately after finalize (no claim needed), expires
-  in 24 h. Give the user the `claimUrl` — claiming keeps it forever on a free
-  account. Until claimed, anonymous pages are served with a small injected
-  claim banner + OG meta tags — expected, not corruption. If no human is
-  present right now, save the `claimToken` (it's also the update key); a
-  fresh device flow can be started later via
-  POST /api/v1/auth/device/start {"agent_name":"..."}.
-- API key (`shiply login` or POST /api/auth/agent/request-code →
-  verify-code): publishes are permanent and manageable.
-- Paid plans add vanity handles (<name>.shiply.now), more custom domains,
-  storage, analytics: https://shiply.now/dashboard/plan
-
-## Everything else — read the topic file first
-
-The files below sit next to this one in `references/` (installed with the
-skill). Hosted copies: `https://shiply.now/skill/references/<file>`. Each is
-self-contained — read the one matching the task before improvising; each
-covers its CLI commands, MCP tools, AND REST endpoints.
-
-* [Publishing & site management](references/publishing.md) — static framework
-  build matrix (Vite/Next/Hugo/…), `detect`, SPA mode, `.shiplyignore`,
-  list/delete/rollback/versions, `verify`, stable previews (`--as`),
-  `promote` preview→prod, `--json` output, form-data subcommands.
-* [SSR frameworks](references/ssr-frameworks.md) — deploy SvelteKit, Astro,
-  Qwik, Nuxt/Nitro, React Router v7, Next.js (OpenNext), Hono/raw Workers
-  with server-side rendering.
-* [Custom domains](references/custom-domains.md) — put the user's own domain
-  on a site: one-click OAuth DNS, manual CNAME, primary-subdomain SEO,
-  readiness polling.
-* [Databases](references/databases.md) — per-site SQL: free D1 (SQLite at the
-  edge, browser shim) + Neon Postgres (branching), migrations, per-DB MCP
-  server.
-* [Functions](references/functions.md) — `worker.js` server code on every
-  request: webhooks, cron triggers, secrets, runtime logs (Workers Lite,
-  Developer plan).
-* [Email](references/email.md) — every owned site sends + receives: signup
-  capture, inbox, double-opt-in audiences, broadcasts, BYO sending domains.
-* [Site features](references/site-features.md) — proxy routes (call AI APIs
-  without exposing keys), Site Data (forms/waitlists, zero backend),
-  password/invite-only access, Variables, Drives (private storage),
-  path-mounting, public profile.
-* [Client work](references/client-work.md) — freelancer delivery: customer
-  intake projects + AI briefs, group work by client, e-sign contracts,
-  sell sites on the marketplace.
-* [Authentication for the user's app](references/site-features.md) — shiply
-  does NOT host end-user auth; bring the user's own Clerk/Auth.js/Supabase
-  (pattern in Site features → "Bring your own auth").
-
-## Limits & references
-≤1000 files/site (≤50 inline via MCP), ≤100 MiB/file, 1 GiB total.
-Machine index: https://shiply.now/llms.txt (full single-file version:
-https://shiply.now/llms-full.txt) · What's new: https://shiply.now/changelog.md
-· OpenAPI: https://shiply.now/openapi.json · Docs: https://shiply.now/docs
+---
+name: shiply
+description: "shiply is the production backend for anything an agent builds — publish any app (static or full-stack SSR, any framework) and give it a live URL, custom domain, SQL database, server functions, email, and a marketplace to sell it. Use when the user asks to publish, host, deploy, share, or update a website/page/demo/report/app, or wants a live URL for generated files. Triggers - \"publish this\", \"host this\", \"put this online\", \"give me a link\", \"update the site\", \"deploy my SvelteKit/Astro/Next.js app\", shiply."
+---
+
+---
+
+> **IMPORTANT — npm package name is `shiply-cli`, NOT `shiply`.** A different
+> npm package named `shiply` (an auto-commit watcher) is published by someone
+> else — installing it does NOT give you the shiply.now CLI. Always use
+> `npx -y shiply-cli@latest …` or `npm install -g shiply-cli`. The CLI binary
+> on PATH is still named `shiply` once installed; the warning is only about
+> the npm package name.
+
+> **Skill freshness check.** Shiply ships new capabilities weekly.
+> **This skill: version 0.27.0, last updated 2026-07-11.**
+> To see what changed since your copy was written, fetch
+> `https://shiply.now/changelog.md` (date-grouped, newest first) — if it lists
+> capabilities newer than the date above, re-install with
+> `npx -y shiply-cli@latest skill --force` OR read the live copy at
+> `https://shiply.now/skill.md`.
+
+---
+
+# shiply — the production backend for anything an agent builds
+
+**What it is.** Not static hosting. shiply takes whatever you build — a static page or a full-stack app in any framework — and gives it a live URL, a custom domain, a SQL database, server functions, email (send + receive), and a marketplace to sell it. One call. No account needed to start: anonymous sites are live immediately, last 24 hours, and can be claimed to keep.
+
+**Why use it.** Ship a complete, working product without stitching together a host + database + email + registrar + payments — it's one agent-native platform (MCP / CLI / REST parity). Hard-ceiling pricing ($0/$8/$24, plus a $49 Studio tier for client delivery — no usage meter on any tier), so a spike or DDoS can never become a surprise bill for the owner.
+
+**How (quickstart).** `shiply publish ./dir` (CLI) — or POST /api/v1/publish → PUT each file → POST finalize — returns a live URL + claimToken.
+
+**NEVER create a new site to update an existing one. Always re-publish to the
+same site** (same slug/claimToken) — otherwise you litter subdomains and lose
+the user's URL.
+
+**Re-publishing the same site is cheap — always prefer it over a new site.**
+Unchanged files are hash-skipped, and an unchanged SSR worker bundle skips
+redeploy entirely (fingerprinted against what's already live). A zero-change
+`shiply publish` on the same site completes in seconds, even for large SSR
+apps — so iterate freely by re-publishing, never by spinning up a fresh site.
+
+This file covers the core path: publish → authorize → update → claim → verify.
+Everything else (databases, domains, SSR, email, functions, client work) lives
+in the **topic files indexed at the bottom** — read the one that matches the
+task before improvising.
+
+## First publish on a new machine: ask for a permanent key in one step
+
+On a no-Bearer publish, include `"agentName": "<your-tool-name>"` in the body
+(e.g. `"Claude Code"`, `"Cursor"`). The response will include a `deviceAuth`
+object alongside the usual `claimUrl`:
+
+```
+"deviceAuth": {
+  "user_code": "ABCD-EFGH",
+  "device_code": "<long opaque token, keep private>",
+  "verification_url": "https://shiply.now/auth/ABCD-EFGH",
+  "poll_url": "https://shiply.now/api/v1/auth/device/poll",
+  "expires_in": 900,
+  "interval": 2
+}
+```
+
+Tell the user once, in plain language:
+
+> Your site is live at <siteUrl>. To keep it forever AND let me publish more
+> without re-pasting, open <verification_url> and click Allow.
+
+Then immediately poll `verification_url`'s sibling endpoint until the user
+acts:
+
+```
+POST https://shiply.now/api/v1/auth/device/poll
+{"device_code": "<the device_code from the response>"}
+```
+
+The response is one of `{status:"pending"}` (keep polling at `interval`s),
+`{status:"approved", api_key:"shp_...", slug_claimed:"..."}` (PERSIST the key —
+see "Save the key" below — the site is now permanent; Allow does both jobs in
+one click), `{status:"expired"|"denied"|"consumed"}` (stop). Cap your polling at
+the announced `expires_in` and respect `interval` — don't tight-loop.
+
+After approval, every future publish uses `Authorization: Bearer <api_key>`
+and the user's dashboard shows their sites without any further claiming.
+
+### Save the key — so EVERY future site is seamless (do this once)
+
+Write the key to **`~/.shiply/credentials`** as `{"apiKey":"shp_..."}` (chmod
+600) — the exact file the shiply CLI reads. This is what makes "one Allow, ever"
+work: from then on every publish (any site, any project, ANY FUTURE SESSION)
+sends `Authorization: Bearer <key>` automatically and lands owned in the user's
+dashboard — no re-authorizing, no claim step, zero clicks. An env var alone
+(`SHIPLY_API_KEY`) works for the current shell but does NOT survive a new
+session — the credentials file is what makes it permanent. `shiply login` writes
+this file for you; if you publish over raw HTTP, write it yourself.
+
+## When the user pastes you something shiply-shaped, do this
+
+These are the patterns you will see. Match the input, run the action — do not
+ask the user to repeat themselves or explain.
+
+- **Code like `SHIPLY-XXXXXXXX`** → it's a pairing code from
+  `shiply.now/claim/<slug>?pair=1`. The user wants to attach an anonymous
+  site to their account. Run `shiply claim verify SHIPLY-XXXXXXXX` from the
+  directory you originally published from (it reads `.shiply.json`). No CLI?
+  POST `https://shiply.now/api/v1/claim/pair/SHIPLY-XXXXXXXX/verify` with
+  `{"siteId":"...","claimToken":"..."}` taken from your earlier publish
+  response or `.shiply.json`. The user's browser auto-redirects on success;
+  tell them to switch back to it.
+- **URL like `https://shiply.now/claim/<slug>?token=...`** → one-click claim
+  link. Tell the user to open it in the browser they are signed in to —
+  do NOT call any API yourself.
+- **User says "claim my site" / "save it forever" with no code or URL** →
+  give them the `claimUrl` from your last publish response. If you no longer
+  have that response but `.shiply.json` is in the publish dir, reconstruct it
+  as `https://shiply.now/claim/<slug>?token=<claimToken>` from those fields.
+  Either way, also suggest `shiply login` so future publishes mint to their
+  account directly — that's the long-term fix and how the dashboard works.
+- **User says "I have an API key now, use it from now on"** → persist it to
+  `~/.shiply/credentials` (`{"apiKey":"shp_..."}`, chmod 600 — see "Save the
+  key" above), then send `Authorization: Bearer <key>` on every future publish.
+  All future sites are then permanent and appear in their dashboard
+  automatically — across sessions, with no re-authorizing.
+- **User opens an `https://shiply.now/auth/XXXX-YYYY` URL you printed** → no
+  action from you; they're on the device-flow consent screen. Keep polling
+  `poll_url` (see "First publish on a new machine" above). The poll response
+  will flip from `pending` to `approved` (with `api_key`) the moment they
+  click Allow.
+
+## Pick your interface (best first)
+
+### 1. MCP (native tools)
+If the `shiply` MCP server is connected (https://shiply.now/mcp), use
+`publish_site`. Every result includes a `toUpdate` field telling you the exact
+call for updates — follow it, and a `shareSuggestion` you can relay to the user.
+Core tools: `site_status`, `list_sites`, `get_site`, `delete_site`, `whoami`,
+`duplicate_site`, `set_variable`, `get_analytics`, `set_handle`. There are
+100+ tools in total — call `tools/list` for the authoritative set; the topic
+files below name the tools for their area (domains, databases, email,
+functions, projects, contracts, marketplace, drives).
+
+### 2. CLI
+```bash
+# IMPORTANT: the npm package is `shiply-cli`, not `shiply` (different package).
+npm i -g shiply-cli        # or: npx -y shiply-cli@latest <command>
+                           # or: curl -fsSL https://shiply.now/install.sh | bash
+shiply publish ./dir       # live URL + confetti
+shiply publish ./dir       # run AGAIN after edits → updates the SAME site
+shiply status <slug> --wait  # SSL + readiness; prints SSL_READY / SITE_READY
+shiply login               # email code → API key → sites become permanent
+shiply claim verify <code> # confirm a SHIPLY-XXXXXXXX pairing code from /claim/<slug>?pair=1
+                           # (uses .shiply.json from CWD; pairs agent session to user's browser)
+```
+The CLI stores each directory's site in `.shiply.json` (slug + update token),
+so repeat publishes reuse the URL automatically. `--new-site` opts out.
+Gitignore `.shiply.json` in public repos. Parse `SITE_READY` / `SSL_READY`
+lines for automation; exit code 0 = ready. For a static framework build
+(Vite, Next export, Hugo, …) publish the BUILD OUTPUT, not the source — run
+`shiply detect` to see what the CLI found; the full framework matrix is in
+[references/publishing.md](references/publishing.md).
+
+### 3. Raw HTTP (no installs)
+```
+1. POST https://shiply.now/api/v1/publish   (Content-Type: application/json)
+   {
+     "agentName": "<your tool name, e.g. Claude Code, Cursor, Codex>",
+     "files": [{"path":"index.html","size":<bytes>,"contentType":"text/html","hash":"<sha256 lowercase hex, optional>"}]
+   }
+   (+ "Authorization: Bearer shp_…" for permanent owned sites)
+2. PUT each file's bytes to response upload.uploads[].url
+3. POST upload.finalizeUrl with {"versionId":"<upload.versionId from step 1>"}
+   → both the publish and finalize responses include a "toUpdate" string: the
+     exact call to update THIS site next time. Follow it — never create a new one.
+```
+
+**ALWAYS include `agentName` on anonymous publishes.** The response then
+carries `deviceAuth` ({user_code, verification_url, poll_url, device_code,
+expires_in, interval}) alongside `claimUrl`. Show the user `verification_url`,
+poll `poll_url` every `interval` seconds with the `device_code`, and on
+`{status:"approved"}` you get a permanent `api_key` PLUS the linked site
+is claimed in the same Allow click. Without `agentName` the user has to
+do a separate manual claim step every time.
+
+**Updates (the response tells you how):** every publish/finalize response
+includes a `toUpdate` string with the exact call — follow it verbatim. In short:
+anonymous → include `"claimToken":"..."` (returned ONCE by the first publish —
+save it); owned → include `"slug":"..."`. Hashes make updates cheap: unchanged
+files are skipped server-side.
+
+## Verify before you say "done"
+
+`shiply status <slug> --wait` polls until the site serves (exit 0, prints
+`SITE_READY` / `SSL_READY`). `shiply verify <slug>` runs a deeper edge
+SSL + HTTP + thumbnail check and prints a stable machine marker line
+`VERIFY status=LIVE http=200 ssl=valid …` — parse that line in automation.
+More manage commands (list, delete, rollback, promote, stable previews) are
+in [references/publishing.md](references/publishing.md).
+
+## The lifecycle to explain to users
+- Anonymous site: live immediately after finalize (no claim needed), expires
+  in 24 h. Give the user the `claimUrl` — claiming keeps it forever on a free
+  account. Until claimed, anonymous pages are served with a small injected
+  claim banner + OG meta tags — expected, not corruption. If no human is
+  present right now, save the `claimToken` (it's also the update key); a
+  fresh device flow can be started later via
+  POST /api/v1/auth/device/start {"agent_name":"..."}.
+- API key (`shiply login` or POST /api/auth/agent/request-code →
+  verify-code): publishes are permanent and manageable.
+- Paid plans add vanity handles (<name>.shiply.now), more custom domains,
+  storage, analytics: https://shiply.now/dashboard/plan
+
+## Everything else — read the topic file first
+
+The files below sit next to this one in `references/` (installed with the
+skill). Hosted copies: `https://shiply.now/skill/references/<file>`. Each is
+self-contained — read the one matching the task before improvising; each
+covers its CLI commands, MCP tools, AND REST endpoints.
+
+* [Publishing & site management](references/publishing.md) — static framework
+  build matrix (Vite/Next/Hugo/…), `detect`, SPA mode, `.shiplyignore`,
+  list/delete/rollback/versions, `verify`, stable previews (`--as`),
+  `promote` preview→prod, `--json` output, form-data subcommands.
+* [SSR frameworks](references/ssr-frameworks.md) — deploy SvelteKit, Astro,
+  Qwik, Nuxt/Nitro, React Router v7, Next.js (OpenNext), Hono/raw Workers
+  with server-side rendering.
+* [Custom domains](references/custom-domains.md) — put the user's own domain
+  on a site: one-click OAuth DNS, manual CNAME, primary-subdomain SEO,
+  readiness polling.
+* [Databases](references/databases.md) — per-site SQL: free D1 (SQLite at the
+  edge, browser shim) + Neon Postgres (branching), migrations, per-DB MCP
+  server.
+* [Functions](references/functions.md) — `worker.js` server code on every
+  request: webhooks, cron triggers, secrets, runtime logs (Workers Lite,
+  Developer plan).
+* [Email](references/email.md) — every owned site sends + receives: signup
+  capture, inbox, double-opt-in audiences, broadcasts, BYO sending domains.
+* [Site features](references/site-features.md) — proxy routes (call AI APIs
+  without exposing keys), Site Data (forms/waitlists, zero backend),
+  password/invite-only access, Variables, Drives (private storage),
+  path-mounting, public profile.
+* [Client work](references/client-work.md) — freelancer delivery: customer
+  intake projects + AI briefs, group work by client, e-sign contracts,
+  sell sites on the marketplace.
+* [Authentication for the user's app](references/site-features.md) — shiply
+  does NOT host end-user auth; bring the user's own Clerk/Auth.js/Supabase
+  (pattern in Site features → "Bring your own auth").
+
+## Limits & references
+≤1000 files/site (≤50 inline via MCP), ≤100 MiB/file, 1 GiB total.
+Machine index: https://shiply.now/llms.txt (full single-file version:
+https://shiply.now/llms-full.txt) · What's new: https://shiply.now/changelog.md
+· OpenAPI: https://shiply.now/openapi.json · Docs: https://shiply.now/docs

package/skill/references/ssr-frameworks.md

@@ -1,47 +1,57 @@
----
-type: reference
-title: SSR frameworks
-description: Deploy full server-side-rendered apps — SvelteKit, Astro, Qwik, the Nitro family (Nuxt, SolidStart, Analog, TanStack Start), React Router v7, Next.js via OpenNext, and Hono/raw Workers.
-timestamp: 2026-07-04
----
-
-# SSR / server frameworks (live: every major JS framework)
-
-Part of the shiply skill (see SKILL.md for publish basics). Requires sign-in +
-Developer plan.
-
-`shiply publish` auto-detects an SSR build and deploys the worker bundle with
-`nodejs_compat`, serving static assets from the edge. Live and verified on prod:
-SvelteKit (`@sveltejs/adapter-cloudflare`), Astro (`@astrojs/cloudflare`), Qwik
-City, the Nitro family (Nuxt, SolidStart, Analog, TanStack Start), React Router
-v7, and Next.js (via OpenNext) — plus wrangler workers (`wrangler.toml` with
-`main` — Hono, itty-router, raw `fetch`). **Build first** (`npm run build`),
-then `shiply publish .`. Force the static path with `--framework=<name>`, or
-skip SSR detection entirely with `--no-ssr`.
-
-Per-framework build setup:
-
-- **SvelteKit** — `@sveltejs/adapter-cloudflare`, then `npm run build`,
-  `shiply publish .`
-- **Astro** — `@astrojs/cloudflare` adapter, `npm run build`, `shiply publish .`
-- **Qwik City** — `@builder.io/qwik-city` cloudflare-pages adapter,
-  `npm run build`, `shiply publish .`
-- **Nitro family (Nuxt, SolidStart, Analog, TanStack Start)** — build with the
-  `cloudflare`(-module) Nitro preset, then `shiply publish .`
-- **React Router v7** — framework mode (`@react-router/dev`), `react-router
-  build`, then `shiply publish .`
-- **Next.js** — build via `@opennextjs/cloudflare` (OpenNext), then
-  `shiply publish .`. Plain SSR works today; **ISR / on-demand revalidate is
-  not live yet**, and Next 16 must build with `next build --webpack` (not
-  Turbopack).
-- **Wrangler workers** — any repo with `wrangler.toml` declaring `main`
-  (Hono, itty-router, raw `fetch` handler) deploys as-is.
-
-How serving works: the deployed worker receives every request; static assets
-are tried first (the worker calls `env.ASSETS`, 200 = asset served from the
-edge / 404 = your SSR handler runs). The worker gets the same bindings,
-secrets, and crons as Functions — see [functions.md](functions.md). Bundle
-cap 8 MB.
-
-Plan gate: Free/Hobby get `402 payment_required` — upgrade at
-https://shiply.now/dashboard/plan.
+---
+type: reference
+title: SSR frameworks
+description: Deploy full server-side-rendered apps — SvelteKit, Astro, Qwik, the Nitro family (Nuxt, SolidStart, Analog, TanStack Start), React Router v7, Next.js via OpenNext, and Hono/raw Workers.
+timestamp: 2026-07-04
+---
+
+# SSR / server frameworks (live: every major JS framework)
+
+Part of the shiply skill (see SKILL.md for publish basics). Requires sign-in +
+Developer plan.
+
+`shiply publish` auto-detects an SSR build and deploys the worker bundle with
+`nodejs_compat`, serving static assets from the edge. Live and verified on prod:
+SvelteKit (`@sveltejs/adapter-cloudflare`), Astro (`@astrojs/cloudflare`), Qwik
+City, the Nitro family (Nuxt, SolidStart, Analog, TanStack Start), React Router
+v7, and Next.js (via OpenNext) — plus wrangler workers (`wrangler.toml` with
+`main` — Hono, itty-router, raw `fetch`). **Build first** (`npm run build`),
+then `shiply publish .`. Force the static path with `--framework=<name>`, or
+skip SSR detection entirely with `--no-ssr`.
+
+Per-framework build setup:
+
+- **SvelteKit** — `@sveltejs/adapter-cloudflare`, then `npm run build`,
+  `shiply publish .`
+- **Astro** — `@astrojs/cloudflare` adapter, `npm run build`, `shiply publish .`
+- **Qwik City** — `@builder.io/qwik-city` cloudflare-pages adapter,
+  `npm run build`, `shiply publish .`
+- **Nitro family (Nuxt, SolidStart, Analog, TanStack Start)** — build with the
+  `cloudflare`(-module) Nitro preset, then `shiply publish .`
+- **React Router v7** — framework mode (`@react-router/dev`), `react-router
+  build`, then `shiply publish .`
+- **Next.js** — build via `@opennextjs/cloudflare` (OpenNext), then
+  `shiply publish .`. Plain SSR works today; **ISR / on-demand revalidate is
+  not live yet**, and Next 16 must build with `next build --webpack` (not
+  Turbopack). `shiply publish` runs a **PREFLIGHT** on Next source dirs: it
+  auto-fixes Turbopack build scripts, translates `vercel.json` crons to
+  `.shiply/crons.json`, and refuses to publish raw source with no worker
+  build — read its `FIX`/`WARN` lines, do what they say, re-run.
+
+  Publish output is self-describing — trust it over memory: finalize streams
+  per-phase progress lines, a failed worker deploy prints a structured `fix:`
+  line to execute verbatim, and after every worker deploy the server probes
+  the live site — a non-zero exit with a `runtime error:` line means
+  DEPLOYED BUT BROKEN (the actual worker exception + likely fix are printed,
+  e.g. a missing `shiply secret set`); fix the printed cause and republish.
+- **Wrangler workers** — any repo with `wrangler.toml` declaring `main`
+  (Hono, itty-router, raw `fetch` handler) deploys as-is.
+
+How serving works: the deployed worker receives every request; static assets
+are tried first (the worker calls `env.ASSETS`, 200 = asset served from the
+edge / 404 = your SSR handler runs). The worker gets the same bindings,
+secrets, and crons as Functions — see [functions.md](functions.md). Bundle
+cap 8 MB.
+
+Plan gate: Free/Hobby get `402 payment_required` — upgrade at
+https://shiply.now/dashboard/plan.