Cloudbase Sites Runtime

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 host=0.0.0.0 forcing, port allocation (17173..17272), daemonization, base path injection, version metadata, and deploy history.

3. Standard tools (Bash, git, Edit, Write)

Use for editing files. The plugin's PostToolUse hook handles automatic restart on config-file edits — you don't need to manage that.

Lifecycle hooks and fallback

Do NOT invoke cloudbase-sites init or cloudbase-sites preview proactively in your first message just because the plugin is installed. SessionStart is intentionally passive for empty directories so the plugin does not interfere with unrelated sessions. A UserPromptSubmit hook may initialize after the first user message, but only when deterministic Chinese/English intent rules detect an explicit Sites/Web-app creation request. By the time you read the user's first prompt:

• If the cwd was an existing Vite project: dev server is up (or installing).
• If the cwd was empty: no files were downloaded by SessionStart. If the first prompt clearly asked to build/create a Sites app, UserPromptSubmit may have started init --start; otherwise initialize only after the user asks.
• If the cwd is a non-Vite / blacklisted project: hook stayed silent.

Codex supports bundled plugin hooks, but non-managed command hooks may require the user to review and trust them before they run. If Codex hooks have not run, resolve the CLI path as described above, then fall back to <cloudbase-sites-cli> preview --status, <cloudbase-sites-cli> init, and the other explicit commands below instead of assuming automatic startup.

If SessionStart reports that it skipped a non-empty non-Vite cwd, do not assume the runtime is active. If a template is downloaded later through MCP downloadTemplate, run <cloudbase-sites-cli> preview --status and then <cloudbase-sites-cli> preview if no preview is running.

You only invoke a CLI verb when:

• User asks to create/build a new Sites app in an empty cwd → cloudbase-sites init --start
• User explicitly says "stop the dev server" → cloudbase-sites preview --stop
• User asks for the URL or "is it running" → cloudbase-sites preview --status
• User wants to save a version → cloudbase-sites save -m "<label>"
• User wants to deploy → cloudbase-sites deploy (then bridge to manageApps)
• User wants to roll back → cloudbase-sites rollback

When the user just walked into the conversation

1. Read the SessionStart status first. If it says the cwd is passive/empty, do not assume a project exists. Wait for the user's first concrete Sites app request, then run cloudbase-sites init --start.

2. For existing Vite projects, check preview state — read <cwd>/.cloudbase-sites/preview.json or run cloudbase-sites preview --status. If no preview is running, start it with cloudbase-sites preview.

3. Tell the user the URL — surface internalUrl from the JSON. If the file is missing after init/preview, inspect .cloudbase-sites/logs/.

4. Offer to open the preview. Ask: "要不要我用内置浏览器打开 <URL> 预览一下?" If yes, use the host Browser / in-app browser tool to open internalUrl. Do not use macOS open, and do not run browser interaction tests unless the user explicitly asks you to test the UI.

5. DO NOT re-init / re-start. Calling init again will fail with code 10 (cwd no longer empty). Calling preview is idempotent and safe but wastes a turn.

6. NEVER guess the port. It is NOT 5173/5174/5175 — the plugin uses 17173..17272. Always read the recorded port from preview.json.

Two-stage save → deploy workflow

Inspired by Codex Sites' saved version model:

• Save: label a git checkpoint. cloudbase-sites save -m "<label>" runs git init when needed, then git add -A && git commit && git tag version/<n> and appends to <cwd>/.cloudbase-sites/app.json.versions[]. No build, no deploy.
• Deploy: publish a saved version to a CloudApp. cloudbase-sites deploy [--version <n>] (default: latest saved) builds dist/ locally then emits nextAction telling you to call manageApps({ action: "deployApp", serviceName: <stable from app.json>, filePath: cwd, buildPath: "dist", framework: "static", installCmd: "", buildCmd: "" }). The framework=static shape skips remote install/build because we built locally.
• Record: after manageApps succeeds and gives you the access URL, call cloudbase-sites deploy --post --version <n> --access-url <url> --build-id <BuildId> [--version-name <VersionName>]. This appends to app.json.deployments[], records CloudBase build metadata, tags git deploy/<n>-<ts>, and returns finalUrl with a cache-busting query. If the manageApps result includes BuildId, you MUST pass it to --build-id; otherwise future build status and log queries cannot be traced directly from the saved deployment.
• Rollback: cloudbase-sites rollback [--to-version <n>] (default: current production deploy). Stashes uncommitted edits, git reset --hard to the version's commit, marks newer versions as rolled-back, and restarts the dev server.

Why CloudApp (manageApps) not static hosting? Each CloudApp has its own subdomain (*.webapps.tcloudbase.com); two vibe sessions on the same env never collide. The stable siteName in app.json ensures re-deploys preserve the URL.

Pre-flight: if manageApps fails with "no envId" / env-related error, call queryEnv({ action: "info" }). If multiple envs exist, ask the user to pick. After binding, retry the deploy.