/cloudbase-sites-runtime

name: cloudbase-sites-runtime
description: |
  Use when the user wants to develop, run, preview, save, deploy, or roll back
  a CloudBase Web app in this conversation as a Lovable/Codex-Sites-like vibe-
  coding session — i.e. any request that maps to "spin up a React+Vite project,
  see it live in the browser, iterate, save versions, deploy". Activate ONLY
  for browser-rendered Web projects based on the CloudBase official React
  (or Vue) + Vite template. Do NOT activate for: WeChat/Alipay mini-program,
  React Native / Flutter / Electron, pure cloud functions / CloudRun backends,
  or Next.js / Nuxt / Astro / Remix / SvelteKit (those frameworks are
  explicitly out of scope).

CloudBase Sites Runtime

This skill orchestrates a **single working directory = single project** flow for CloudBase Web apps. The cwd itself is the workspace; we do not manage cross-cwd state or session IDs at the skill level.

This runtime is shared by the Codex, Claude Code, and CodeBuddy plugin surfaces. The CLI and CloudBase MCP workflows are the source of truth. Some hosts also run bundled lifecycle hooks that start previews or inject compact rules at session start; if hooks are unavailable, disabled, or not yet trusted, use the explicit CLI commands in this skill.

Activation contract

Use this skill when

• The user says "build me a website / app", "I want to make a landing page",

"create a React app and let me preview", "deploy this to CloudBase", "save this version", "roll back to v1", or similar.

• The current cwd looks like a CloudBase + Vite project (has `package.json`

with `vite` + `react` or `vue`).

• The user is running this conversation inside Codex, Claude Code, CodeBuddy,

or a compatible host with the `cloudbase-sites` plugin enabled — `cloudbase-mcp` is registered and the `cloudbase-sites` binary is either on PATH or available from the plugin root's `bin/cloudbase-sites`.

Do NOT use this skill when

• It's a mini-program project — route to mini-program guidance instead.
• It's a native app project — route to http-api guidance.
• It's a backend-only project — route to cloud-functions / cloudrun guidance.
• The framework is Next/Nuxt/Astro/Remix — politely tell the user this skill

only covers Vite-based React/Vue apps and stop. Do NOT try to adapt the scripts to those frameworks.

What this skill orchestrates — three layers

1. CloudBase MCP tools (provided by `cloudbase-mcp`, registered via plugin's `.mcp.json`)

These are the only tools that produce CloudBase side effects. Highlights:

• `downloadTemplate({ template: "react" | "vue", ide })` — pull official template
• `queryEnv({ action: "info" })` + `auth({ action: "set_env", envId })` — bind env
• `manageApps({ action: "deployApp", ... })` — deploy to CloudApp (independent subdomain)
• `envDomainManagement({ action: "create", domains })` — whitelist dev origin for CORS
• `searchKnowledgeBase({ mode: "skill", skillName: "<name>" })` — fetch CloudBase domain skills (see below)

For all CloudBase operations beyond the dev-server lifecycle (auth, db, storage, ai), fetch the corresponding CloudBase domain skill via `searchKnowledgeBase(mode="skill", skillName=...)`. Common ones:

• `ui-design` UI design spec (mandatory before new UI work)
• `web-development` Web project conventions
• `auth-tool-cloudbase` provider config (management-side)
• `auth-web-cloudbase` Web SDK auth client code
• `postgresql-development-cloudbase` PG mode schema/RLS/`app.rdb()` (PG envs)
• `cloudbase-document-database-web-sdk` document database Web SDK
• `cloud-storage-web` cloud storage Web SDK
• `relational-database-web-cloudbase` MySQL Web SDK
• `cloudbase-platform` platform overview / console links

These are **NOT Claude Code native skills** and are NOT bundled with this plugin. They live inside cloudbase-mcp and are fetched on demand. When this file (or the injected RULES_BLOCK) says "调 ui-design skill" or "follow the auth-tool skill", that means: call `searchKnowledgeBase(mode="skill", skillName="<that-name>")` and apply the returned content.

2. The `cloudbase-sites` CLI (provided by this plugin's `bin/` directory)

First resolve the CLI path:

1. Try `command -v cloudbase-sites`. 2. If that fails and the host exposes `CODEX_PLUGIN_ROOT`, use `$CODEX_PLUGIN_ROOT/bin/cloudbase-sites`. 3. If that fails and the host exposes `CLAUDE_PLUGIN_ROOT`, use `$CLAUDE_PLUGIN_ROOT/bin/cloudbase-sites`. 4. If SessionStart injected an absolute CLI path, use that path.

Do not assume Codex has injected the plugin `bin/` directory into PATH.

Single binary, multiple subcommands. Use these — and ONLY these — for the dev-server / version / deploy lifecycle:

• `cloudbase-sites init --start` — scaffold from empty cwd and start preview when the user explicitly wants a Sites app
• `cloudbase-sites preview` — daemonize Vite for an existing Vite project
• `cloudbase-sites preview --status [--quiet]` — JSON status / exit code
• `cloudbase-sites preview --restart` / `--stop [--force]`
• `cloudbase-sites save -m "<label>"` — create a saved version
• `cloudbase-sites versions` — list saved versions + deploy status
• `cloudbase-sites deploy [--version <n>]` — deploy a saved version (Phase 1: emit nextAction)
• `cloudbase-sites deploy --post --version <n> --access-url <url> [--build-id <BuildId>] [--version-name <VersionName>]` — record deploy
• `cloudbase-sites rollback [--to-version <n>]` — revert to a saved version
• `cloudbase-sites supervisor status|list|heal|reload|start|stop`

Never invent `npm run dev` / `vite` / `vite build` invocations. The CLI handles the bind-address policy, port allocation (17173..17272), daemonization, base path injection, version metadata, and deploy history.

The dev server has no authentication and binds `127.0.0.1` by default. Expose it to the network only when the user asks: `preview --host 0.0.0.0` (or `CLOUDBASE_SITES_HOST=0.0.0.0`)