/makers-env-adaption

name: edgeone-makers-env-adaption
description: >-
  Environment-specific adaptation rules for EdgeOne Makers Skills running in
  sandboxed or restricted AI coding environments (e.g. WorkBuddy).
  Trigger when: the user is working in WorkBuddy or a sandboxed IDE where CLI prompts hang and network is proxy-isolated (but browser login still works).
  Covers: non-interactive CLI flags, network isolation workarounds, login in sandbox,
  proxy bypass, file preview constraints (MUST use http:// via dev server, NEVER file://,
  NEVER python -m http.server / npx serve), dev server requirements.
pathPatterns:
  - "*.sh"
  - package.json
validate:
  - pattern: "python\\s+-m\\s+http\\.server|npx\\s+(serve|http-server)"
    message: "Use `edgeone makers dev` — self-hosted static servers skip Blob credentials, Cloud Functions routing, Edge Functions and middleware."
  - pattern: "localhost:80(88|89)"
    message: "Use 127.0.0.1, not localhost — in the sandbox localhost resolves to ::1 and yields false 404s."
metadata:
  author: edgeone
  version: "1.4.2"

Runtime Environment Adaptation Guide

> This document describes the special constraints and adaptation rules for EdgeOne Makers Skills across different AI coding environments. > Currently covered: **WorkBuddy** (Tencent sandboxed IDE)

---

🚦 Quick Reference: Preview Decision Tree

When you reach the "display / preview" step, **read this first before deciding how to call `present_files`**:

            ┌─ Delivering finished work? ── Yes ──→ present_files(deployed EdgeOne URL) ✅
            │
Enter       ┤
preview     │                      ┌─ dev server running? ─ Yes ──→ present_files(http://127.0.0.1:8088/) ✅
            └─ Still iterating? ───┤
                                    └─ No ──→ start edgeone makers dev → present_files(...)

| What you want to do | Correct approach | Wrong approach (breaks) | |---|---|---| | Preview local dev server | `present_files("http://127.0.0.1:8088/")` | ❌ Passing `/path/to/index.html` (IDE opens it via file://) | | Preview a deployed project | `present_files(deploy_url)` with `?eo_token=...` | ❌ Passing a local `dist/index.html` path | | Start dev server | `edgeone makers dev --name <p> --skip-env-sync` | ❌ `python -m http.server` / `npx serve` | | Verify dev server is up (agent-side API check) | `curl --noproxy '*' http://127.0.0.1:8088/api/...` ✅ works (same sandbox) | ❌ `curl localhost:8088` / plain `curl` (proxy + IPv6 → 404/000) | | Verify dev server is up (user-facing) | `present_files(http://127.0.0.1:8088/)` (platform tunnel) | ❌ Telling user to open `127.0.0.1:8088` — their browser can't reach the sandbox |

**Core iron rule**: inside a Makers project, **any HTML / URL preview MUST go through the HTTP protocol**. `file://` looks convenient, but fetch / SSE / Blob / KV all break under it.

Violation symptoms self-check (if you see these, go back up immediately)

• Browser Console: `TypeError: Failed to fetch` / `CORS policy` errors
• Page HTML loads fine but all JS requests 404
• SSE / EventSource disconnects immediately on connect
• Works locally but breaks once deployed (or vice versa)

---

WorkBuddy Sandbox Environment

WorkBuddy is a sandboxed remote IDE environment. When running AI coding tasks, it has the following constraints that differ from local development.

> **⚠️ Common misread: WorkBuddy is a *desktop IDE sandbox*, NOT a headless environment.** > - CLI **interactive prompts** (site picker, confirmations) hang inside the sandbox → use the non-interactive flags in this section. > - **BUT browser login (`edgeone login --site <x>`) works fully** — WorkBuddy launches the host OS browser AND routes the OAuth callback back into the sandbox. > > Deploy/link login should default to browser login and only fall back to `-t <token>` after browser login is confirmed to fail. Do NOT jump to token login just because the caller is an "Agent".

---

1. Non-interactive mode (all CLI commands must avoid interactive prompts)

Inside the WorkBuddy sandbox, CLI interactive prompts cause the process to hang forever. All `edgeone` CLI commands must carry non-interactive flags:

| Scenario | Required flag | Reason | |------|---------|------| | Local development | `--skip-env-sync` | Skips the "sync environment variables?" confirmation | | Linking a project | `--name <project>` | Skips the interactive project picker | | Auth when not logged in | `-t <token>` | Passes the token directly, no login popup | | Deploy output | `--json` | Machine-readable JSON, avoids ANSI parsing |

# Correct: local development
edgeone makers dev --name my-project --skip-env-sync

# Correct: deploy
edgeone makers deploy -n my-project --json

# Wrong: will hang
edgeone makers dev

---

2. Login authentication

**Token resolution priority** (the CLI checks in this order automatically): 1. `-t <token>` command-line argument 2. `EDGEONE_PAGES_API_TOKEN` environment variable 3. `<cwd>/.edgeone/auth.json` (written by `edgeone login --local`) 4. `~/.edgeone/` global credentials

**Recommended approach**: browser login + the `--local` flag:

edgeone login --site china --local

`--local` writes credentials to the project directory at `<cwd>/.edgeone/auth.json`, bypassing home-directory write restrictions.

**Login status detection**:

edgeone whoami  # exit 0 = logged in, exit 1 = not logged in (does not hang)

**When is login actually required?** Login is only needed when the project uses **Blob** or other credentialed backends — and strictly because of the dependency chain: **Blob requires the project to be linked, and linking requires a logged-in account first.** So `edgeone makers dev` for a **pure-static** site runs fine without login — **do NOT force a login prompt for static-only previews**. Login (or `-t <token>`) becomes mandatory the moment dev/deploy must touch Blob storage. (The trigger condition and the link chain live in makers-storage.)

**CLI version requiremen