shiply-cli 0.23.0 → 0.25.0

package/skill/references/publishing.md

@@ -0,0 +1,103 @@
+---
+type: reference
+title: Publishing & site management
+description: Static framework build matrix, detect, SPA mode, .shiplyignore, list/delete/rollback, verify, stable previews, promote, machine-readable output, form-data subcommands.
+timestamp: 2026-07-04
+---
+
+# Publishing & site management
+
+Part of the shiply skill (see SKILL.md for publish basics, auth, and updates).
+Everything here works over CLI, MCP, and REST with a `Authorization: Bearer
+shp_…` key unless marked anonymous-ok.
+
+## Any static site works — frameworks + SSGs auto-detected
+
+shiply hosts any static site (and full SSR apps too — see
+[ssr-frameworks.md](ssr-frameworks.md)). For a static build, publish the BUILD
+OUTPUT, never the source: run the build, then publish the output dir with SPA
+mode for client-routed apps. The CLI auto-detects 16+ frameworks and tells you
+the right command. Run `shiply detect` to preview what it found without
+uploading.
+
+- Vite (React/Vue/Svelte/Solid/Qwik): `npm run build` then `shiply publish dist --spa`
+- Create React App: `npm run build` then `shiply publish build --spa`
+- Next.js (static): set `output: "export"` in next.config, `npm run build`, then
+  `shiply publish out` (no --spa; export emits real HTML per route). For full
+  Next.js SSR (via OpenNext) see [ssr-frameworks.md](ssr-frameworks.md) —
+  plain SSR is live (ISR/revalidate not yet; Next 16 needs
+  `next build --webpack`).
+- Astro: `npm run build` then `shiply publish dist`
+- SvelteKit (adapter-static): `npm run build` then `shiply publish build --spa`
+- Nuxt: `npx nuxt generate` then `shiply publish .output/public`
+- Remix (client build): `npm run build` then `shiply publish build/client --spa`
+- Docusaurus: `npm run build` then `shiply publish build`
+- Hugo: `hugo` then `shiply publish public`
+- Jekyll: `bundle exec jekyll build` then `shiply publish _site`
+- Eleventy: `npx @11ty/eleventy` then `shiply publish _site`
+- MkDocs: `mkdocs build` then `shiply publish site`
+- Hexo: `npx hexo generate` then `shiply publish public`
+- SolidStart (static): `npm run build` then `shiply publish dist/public`
+- Qwik City (static adapter): `npm run build` then `shiply publish dist`
+- Anything else with a built `dist/`/`build/`/`out/`/`_site/`/`public/`/
+  `.output/public/` folder: generic fallback picks it up.
+- Plain HTML: `shiply publish .` — no build step.
+
+Override auto-detection with `--framework=<name>`. Use the CLI (not inline
+MCP files) for builds — hashed bundles often exceed the 50-file inline cap,
+and the CLI hash-skips unchanged chunks on updates.
+
+**SPA mode**: pass `--spa` (CLI) or `"spaMode": true` (REST/MCP) so deep links
+serve index.html.
+
+## Manage & verify sites (CLI)
+
+List, delete, roll back, verify, and promote owned sites — all over the same
+Bearer API key. Great for agents that ship iteratively and need to keep their
+subdomains tidy.
+
+```bash
+shiply ls                                   # list your sites: slug, status, URL
+shiply rm <slug> --yes                      # PERMANENTLY delete a site + its files (--yes required)
+shiply rollback <slug>                      # list finalized versions (current one marked)
+shiply rollback <slug> <versionId>          # re-point the site to that version — live instantly
+shiply verify <slug>                        # edge SSL + HTTP + thumbnail readiness check
+shiply publish <dir> --as <name>            # STABLE preview: same URL every iteration (local alias)
+shiply promote <preview-slug> --to <dest-slug>   # copy the preview's exact live bytes onto a prod site
+shiply publish <dir> --json                 # one machine-readable JSON line, no confetti/banners
+```
+
+- **`shiply verify <slug>`** prints a human report PLUS a stable machine marker
+  line `VERIFY status=LIVE http=200 ssl=valid thumb=…` (or `status=PENDING`).
+  Headless agents should parse that `VERIFY status=…` line — it's the
+  contract, like `SITE_READY` in `status`.
+- **`shiply publish <dir> --as <name>`** gives a stable preview URL that the
+  next publish with the same `--as <name>` reuses — no more changing URLs or
+  orphaned scratch sites across iterations, independent of the source dir.
+- **`shiply promote <preview-slug> --to <dest-slug>`** copies the *exact bytes*
+  you previewed onto an existing owned destination site (keeps its slug,
+  domains, access) — atomic preview→production, no rebuild.
+- **`--json`** on `publish`/`update` emits a single JSON line
+  `{slug,siteUrl,siteId,uploaded,skipped,anonymous,expiresAt,updated}` and
+  suppresses all human output + confetti — use it in scripts/agents.
+- **`.shiplyignore`** in the publish root excludes files from upload
+  (documented gitignore subset: `# comments`, `secret.txt`, `internal/`,
+  `*.log`, `/anchored`, `**` globs, `!negation`). Keep `.env`, notes, and
+  internal files out of the published bytes.
+
+## Rollback + version history (REST/MCP)
+
+- Deploy history: `GET /api/v1/sites/<slug>/versions` (Bearer) →
+  `{versions:[{id,createdAt,isLive,fileCount,bytes}]}` (newest-first, ≤20).
+  MCP tool: `list_versions`.
+- Rollback: `POST /api/v1/publish/<slug>/rollback {"versionId"}` flips any
+  finalized version live instantly. MCP tool: `rollback_site`.
+
+## Reading captured form data from the CLI
+
+To verify captured signups/form data without the dashboard (see
+[site-features.md](site-features.md) for how sites capture data):
+`shiply data list <slug>` (collections + counts),
+`shiply data query <slug> <coll> [--limit N] [--where '<json>']`, and
+`shiply data export <slug> <coll> [--out file.ndjson]`. Confetti is
+suppressed automatically on non-TTY stdout; `--no-confetti` forces it off.

package/skill/references/site-features.md

@@ -0,0 +1,110 @@
+---
+type: reference
+title: Site features (proxy routes, Site Data, access control, variables, drives, auth)
+description: Dynamic capabilities on any owned site — server-side secret proxying for AI/API calls, zero-backend form storage, password/invite-only access, encrypted variables, private drives, path-mounting, public profile, and the bring-your-own-auth pattern.
+timestamp: 2026-07-04
+---
+
+# Site features — the dynamic layer on owned sites
+
+Part of the shiply skill (see SKILL.md for publish basics). Everything here
+requires an OWNED site (claim it first) and applies per-site.
+
+## Proxy routes — AI/API calls WITHOUT exposing keys
+
+NEVER embed API keys in published HTML/JS. Instead: store the key as a
+Variable (PUT /api/v1/variables), then include `.shiply/proxy.json` in the
+published files declaring routes, e.g. {"proxies":{"/api/chat":{"upstream":
+"https://openrouter.ai/api/v1/chat/completions","method":"POST","headers":
+{"Authorization":"Bearer ${OPENROUTER_API_KEY}"}}}}. The page then calls the
+relative path (fetch('/api/chat')) and shiply injects the secret server-side.
+`${VAR}` resolves from the owner's encrypted Variables at request time — keys
+NEVER reach the browser. Prefix routes "/api/db/*" forward subpaths (great
+for Supabase REST). Owned sites only; https public upstreams only;
+100 req/h/ip; 10 MB bodies; SSE streams supported. Docs: /docs/proxy-routes
+
+## Site Data — forms/waitlists/guestbooks with ZERO backend
+
+When the user wants to collect anything from visitors (waitlist, contact
+form, RSVP, guestbook): include `.shiply/data.json` in the published files,
+e.g. {"collections":{"signups":{"fields":{"email":{"type":"email",
+"required":true}},"access":{"read":"owner","insert":"public"},
+"rateLimit":"10/hour/ip"}}}, then have the page POST JSON to the relative
+path /.shiply/data/signups (201 + id; 400 with the exact field error).
+Records are validated server-side; the owner reads them in the dashboard
+(Data section, CSV export) or GET /api/v1/publishes/<slug>/data/<collection>
+with a Bearer key. Field types: string/number/integer/boolean/email/url/
+datetime. Limits: 10 collections, 16 KB records, 25k/collection. Owned sites
+only. CLI readers: `shiply data list/query/insert/export/wipe-collection`
+(see [publishing.md](publishing.md)) and `shiply data init` scaffolds the
+manifest. Docs: /docs/site-data
+
+To also email/confirm/broadcast to captured signups, add an `email` block —
+see [email.md](email.md).
+
+## Access control — password or invite-only sites (paid)
+
+To password-protect or restrict a site: PATCH /api/v1/publishes/<slug>/access
+with {"mode":"password","password":"..."} or {"mode":"restricted",
+"allowedEmails":[...],"allowedDomains":[...]}, or set mode "public" to open it.
+GET returns the policy (never the hash). MCP tool: `set_site_access`. Enforced
+at the edge before any content/proxy/data is served; visitors get a 7-day
+signed cookie; changing any setting signs current visitors out.
+Docs: /docs/access-control
+
+## Variables — encrypted per-user KV
+
+For API keys the user's sites need: GET/PUT /api/v1/variables
+{"name","value"}, DELETE /api/v1/variables/{NAME}; GET ?reveal=1 returns
+plaintext values. MCP: `set_variable`. Referenced by proxy routes (`${VAR}`)
+and injected into Workers as `env.<NAME>`. Supabase can be connected from the
+dashboard and lands here as SUPABASE_URL + SUPABASE_ANON_KEY.
+
+## Drives — private cloud storage (agent memory + assets)
+
+Private storage for files/notes/context you don't want on a public site.
+MCP tools: `list_drives`, `create_drive`, `drive_put_file` (driveId
+"default", utf8/base64, ≤2 MB), `drive_list_files`, `drive_delete_file`,
+`publish_from_drive` (snapshot a drive into a live site).
+
+## Path-mounting + public profile
+
+- `set_link` (MCP) — mount another owned **public** site at a path on a host
+  (host/docs → target).
+- `set_profile` / `feature_site` (MCP) — stand up the user's public portfolio
+  at <handle>.shiply.now and feature a public site on shiply.now/explore.
+- `export_account` (MCP) — JSON bundle of the user's data (no secrets).
+- Site metadata: `PATCH /api/v1/publish/<slug>/metadata`
+  {"title?","spaMode?","addedToProfile?"}.
+
+## Bring your own auth (Clerk / Auth.js / Lucia / Supabase Auth)
+
+shiply does **not** host customer auth. If the user's app needs sign-in, you
+(the agent) set up their auth provider yourself — Clerk is the fastest path.
+
+**One-time human step:** ask the user to create a Clerk app at
+`dashboard.clerk.com` (~2 min). They paste you the publishable key (`pk_…`)
+and secret key (`sk_…`).
+
+**Wire it:**
+```bash
+shiply secret set <slug> CLERK_SECRET_KEY sk_live_xxxxxxxxxx
+# The publishable key can be embedded in the JS build — it's safe in the browser.
+```
+
+**In `worker.ts`:** verify the session JWT against `env.CLERK_SECRET_KEY` on
+every API request (e.g. `@clerk/backend` verifyToken), scope D1 rows by
+`payload.sub` (the Clerk user id).
+
+**In the SPA:** add `@clerk/clerk-react` to the build, wrap with
+`<ClerkProvider>`, attach `Authorization: Bearer <token>` to every
+authenticated fetch.
+
+Why not auto-integrate? shiply's own Clerk instance signs in **agents** to the
+shiply dashboard — it's not multi-tenant for someone else's app's users.
+Customers owning their own Clerk is the only correct shape.
+
+Same pattern works for Auth.js, Lucia, Supabase Auth, Firebase Auth — store
+the provider secret via `shiply secret set`, verify the JWT in the worker.
+
+Docs: https://shiply.now/docs/auth

package/skill/references/ssr-frameworks.md

@@ -0,0 +1,47 @@
+---
+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.