@ducking-mind/proxy-app-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proxy App contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @ducking-mind/proxy-app-cli
+
+CLI for developing, validating, packaging, and publishing applications for the
+Proxy App platform.
+
+## Install
+
+The CLI requires Node.js 20.19 or newer. Install it from npm after the package
+is published:
+
+```bash
+npm install --global @ducking-mind/proxy-app-cli
+```
+
+When working in this repository, run it from the repository root instead:
+
+```bash
+npm run app -- --help
+```
+
+## Commands
+
+`<app-dir>` is the directory containing `manifest.json` and the app's build
+script.
+
+```bash
+# Create a starter app and connect it to a platform app
+proxy-app init apps/my-app --name "My App"
+proxy-app create apps/my-app
+
+# Link an existing local app to a platform app by its platform ID
+proxy-app link apps/my-app <app-id>
+
+# Run the app's own build script and validate the resulting dist/ directory
+proxy-app build apps/my-app
+proxy-app validate apps/my-app
+proxy-app doctor apps/my-app
+
+# Package the built app (manifest.json is placed at the ZIP root)
+proxy-app pack apps/my-app
+
+# Upload a version without submitting it for review
+proxy-app upload apps/my-app
+
+# Upload a missing version and submit it for platform review
+proxy-app publish apps/my-app
+
+# Inspect the local binding and remote version state
+proxy-app status apps/my-app
+```
+
+Release `pack`, `upload`, and `publish` require a successful build and use the
+`dist/` output. `--source` is available on `pack` and `upload` only for local
+debugging; source packages are not release packages. The app manifest version
+must be increased for a new artifact. `publish` submits the version for review;
+it does not bypass platform review or make an app immediately public.
+
+## Management authentication
+
+Management commands (`create`, `link`, `upload`, `publish`, and authenticated
+`status`) use the current platform Portal user's access token. The CLI does not
+provide a `login` command and never passes this token to the app runtime.
+
+1. Sign in to the platform Portal as the app owner.
+2. In the browser developer tools, open the Portal origin's local storage and
+   copy the `access_token` value.
+3. Export it only in the shell used for the command:
+
+```bash
+export PROXY_API_BASE_URL="https://your-platform.example/api"
+printf 'Portal access token: '
+read -rs PROXY_USER_ACCESS_TOKEN
+export PROXY_USER_ACCESS_TOKEN
+printf '\n'
+
+proxy-app create apps/my-app
+proxy-app build apps/my-app
+proxy-app upload apps/my-app
+proxy-app publish apps/my-app
+
+unset PROXY_USER_ACCESS_TOKEN
+```
+
+For a local platform, the default API base is
+`http://localhost:9003/api`. `PROXY_ACCESS_TOKEN` is accepted as a legacy alias
+for `PROXY_USER_ACCESS_TOKEN`. Never commit either variable, browser cookies,
+App Session tokens, or provider credentials.
+
+## Local development
+
+```bash
+proxy-app dev apps/my-app --port 5173
+```
+
+Development uses a loopback Relay and the signed-in user's short-lived App
+Session. The default runtime requests use HTTP. Pass `--legacy-bridge` only when
+running an app that explicitly needs the v1 Bridge compatibility path. The
+management token is not injected into the app process.
+
+See the repository documentation for the manifest, runtime API, and release
+contract:
+
+- [`docs/APP_MARKET.md`](../docs/APP_MARKET.md)
+- [`docs/API_REFERENCE.md`](../docs/API_REFERENCE.md)
+- [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md)

package/local-dev-relay.mjs

@@ -0,0 +1,438 @@
+import { createServer } from 'node:http'
+import { randomUUID } from 'node:crypto'
+import { Readable } from 'node:stream'
+
+const HOP_BY_HOP_HEADERS = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade'])
+const SENSITIVE_HEADERS = new Set(['host', 'authorization', 'cookie', 'origin', 'referer', 'content-length', 'x-proxy-app-relay'])
+const PLATFORM_AUTH_TIMEOUT_MS = 30 * 1000
+
+function copyRequestHeaders(request) {
+  const headers = new Headers()
+  for (const [name, value] of Object.entries(request.headers)) {
+    const lower = name.toLowerCase()
+    if (HOP_BY_HOP_HEADERS.has(lower) || SENSITIVE_HEADERS.has(lower)) continue
+    if (Array.isArray(value)) headers.set(name, value.join(', '))
+    else if (value !== undefined) headers.set(name, value)
+  }
+  return headers
+}
+
+function copyResponseHeaders(response, target) {
+  response.headers.forEach((value, name) => {
+    const lower = name.toLowerCase()
+    if (!HOP_BY_HOP_HEADERS.has(lower) && !['content-encoding', 'content-length', 'set-cookie'].includes(lower)) target.setHeader(name, value)
+  })
+}
+
+async function readBody(request, limit = 16 * 1024 * 1024) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of request) {
+    size += chunk.length
+    if (size > limit) throw new Error('local development request body is too large')
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks)
+}
+
+async function readJSON(response) {
+  const text = await response.text().catch(() => '')
+  if (!text.trim()) return {}
+  try { return JSON.parse(text) } catch { return { message: text } }
+}
+
+function unwrap(payload) {
+  return payload && Object.prototype.hasOwnProperty.call(payload, 'data') ? payload.data : payload
+}
+
+function errorMessage(payload, fallback) {
+  const error = typeof payload?.error === 'string' ? payload.error : payload?.error?.message
+  return error || payload?.message || fallback
+}
+
+function errorCode(payload) {
+  const error = payload?.error
+  const code = typeof error === 'object' && error ? error.code : undefined
+  return String(code || payload?.code || '').trim()
+}
+
+async function retryableSessionExpiry(response, runtimeRequest) {
+  if (response?.status !== 401) return false
+  const payload = await readJSON(response.clone())
+  const error = payload?.error
+  const reason = typeof error === 'object' && error ? error.auth_reason : undefined
+  const executionStarted = typeof error === 'object' && error && Object.prototype.hasOwnProperty.call(error, 'execution_started')
+    ? error.execution_started
+    : payload?.execution_started
+  return (runtimeRequest ? errorCode(payload) : reason) === 'APP_SESSION_EXPIRED' && executionStarted === false
+}
+
+function relayError(code, message, stage, statusCode = 502, cause) {
+  const error = new Error(message)
+  error.code = code
+  error.stage = stage
+  error.statusCode = statusCode
+  if (cause) error.cause = cause
+  return error
+}
+
+function visibleErrorMessage(error) {
+  switch (error?.code) {
+    case 'APP_PLATFORM_UNAVAILABLE': return '无法连接平台，请确认平台服务已启动或网络可用后重试。'
+    case 'APP_PLATFORM_TIMEOUT': return '平台响应超时，请稍后重试。'
+    case 'APP_LOGIN_SESSION_EXPIRED': return '平台登录态已失效，请重新登录。'
+    case 'APP_LOGIN_NOT_ALLOWED': return '当前账户无权使用此应用，请切换账户后重试。'
+    case 'APP_APP_REGISTRATION_FAILED':
+      if (error?.upstreamCode === 'APP_LOCAL_MANIFEST_CONFLICT' || error?.message === 'local development version already exists with a different manifest; bump manifest.version') return '平台登录已完成，但本地 manifest 与已上传或发布的同版本内容不同。请更新 manifest.version 后重启 proxy-app dev。'
+      if (error?.statusCode === 403) return '当前登录账户无权开发此应用，请使用创建该应用的账户登录。'
+      if (error?.statusCode === 404) return '应用不存在，或当前账户不是应用创建者。请检查 .proxy-app.json 中的应用绑定。'
+      return '应用开发登记失败（HTTP ' + error?.statusCode + '），请根据请求编号检查平台日志。'
+    case 'APP_SESSION_CREATE_FAILED': return '用户 App Session 创建失败，请稍后重试。'
+    case 'APP_SESSION_INVALID': return '平台返回的用户 App Session 无效，请稍后重试。'
+    default: return String(error?.message || '平台登录失败，请重试。').slice(0, 240)
+  }
+}
+
+function htmlEscape(value) {
+  return String(value).replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[character]))
+}
+
+function safeScriptJSON(value) {
+  return JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}
+
+function safeURL(value, label) {
+  let parsed
+  try { parsed = new URL(value) } catch { throw new Error(label + ' must be a valid http(s) URL') }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error(label + ' must be an http(s) URL without credentials, query, or hash')
+  }
+  return parsed.origin + parsed.pathname.replace(/\/$/, '')
+}
+
+function normalizeGatewayURL(value) {
+  const normalized = safeURL(value, 'platform returned gateway URL')
+  return normalized.endsWith('/v1') ? normalized : normalized + '/v1'
+}
+
+function jsonResponse(response, status, payload) {
+  response.statusCode = status
+  response.setHeader('Content-Type', 'application/json')
+  response.setHeader('Cache-Control', 'no-store')
+  response.end(JSON.stringify(payload))
+}
+
+/**
+ * Real local development relay. It stores only the current signed-in user's
+ * Portal token in memory and gives the app an App Session, never the Portal
+ * token. The token is obtained through the platform login callback, not from
+ * the developer's shell environment, so model calls belong to the user who
+ * opened the local app.
+ */
+export async function createLocalDevelopmentRelay({ baseURL, portalURL = '', relaySecret, appID, appSlug, version, manifest, entryURL, legacyBridge = false }) {
+  if (!baseURL || !relaySecret || !appID || !appSlug || !version || !entryURL) throw new Error('local development relay configuration is incomplete')
+  const portal = safeURL(baseURL, 'platform API URL')
+  const portalOrigin = safeURL(portalURL || portal, 'platform Portal URL')
+  const state = { portalToken: '', session: null, refresh: null, login: null, authGeneration: 0, authState: '', authStateIssuedAt: 0, closed: false, revoked: new Set() }
+  let server
+  let relayURL = ''
+
+  const portalJSON = async (path, init = {}, stage = 'platform', authToken) => {
+    const token = authToken === undefined ? state.portalToken : authToken
+    if (!token) {
+      throw relayError('APP_LOGIN_REQUIRED', 'platform user login is required', stage, 401)
+    }
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), PLATFORM_AUTH_TIMEOUT_MS)
+    let response
+    try {
+      response = await fetch(portal + path, {
+        ...init,
+        signal: controller.signal,
+        headers: { Authorization: 'Bearer ' + token, ...(init.headers || {}) },
+      })
+    } catch (error) {
+      clearTimeout(timeout)
+      if (error?.name === 'AbortError') throw relayError('APP_PLATFORM_TIMEOUT', 'platform request timed out', stage, 504, error)
+      throw relayError('APP_PLATFORM_UNAVAILABLE', 'platform request could not be reached', stage, 502, error)
+    }
+    clearTimeout(timeout)
+    const payload = await readJSON(response)
+    if (!response.ok) {
+      if (response.status === 401) throw relayError('APP_LOGIN_SESSION_EXPIRED', 'platform user session expired', stage, 401)
+      if (response.status === 403) throw relayError('APP_LOGIN_NOT_ALLOWED', 'platform user is not allowed to use this app', stage, 403)
+      const code = stage === 'app_registration' ? 'APP_APP_REGISTRATION_FAILED' : stage === 'app_session' ? 'APP_SESSION_CREATE_FAILED' : 'APP_PLATFORM_REQUEST_FAILED'
+      const failure = relayError(code, errorMessage(payload, 'platform request failed: HTTP ' + response.status), stage, response.status)
+      failure.requestId = response.headers.get('x-request-id') || ''
+      failure.upstreamCode = errorCode(payload)
+      throw failure
+    }
+    return unwrap(payload)
+  }
+
+  const revoke = async (session, authToken) => {
+    const id = session?.session_id
+    if (!id || state.revoked.has(id) || !(authToken === undefined ? state.portalToken : authToken)) return
+    state.revoked.add(id)
+    await portalJSON('/portal/user/apps/' + encodeURIComponent(appID) + '/sessions/' + encodeURIComponent(id), { method: 'DELETE' }, 'platform', authToken).catch(() => undefined)
+  }
+
+  const clearAuthentication = async () => {
+    const current = state.session
+    const token = state.portalToken
+    state.authGeneration += 1
+    state.session = null
+    state.portalToken = ''
+    state.refresh = null
+    state.login = null
+    state.authState = ''
+    state.authStateIssuedAt = 0
+    await revoke(current, token)
+  }
+
+  const assertAuthentication = (generation) => {
+    if (state.closed) throw new Error('local development relay is closed')
+    if (generation !== state.authGeneration) throw relayError('APP_AUTH_CHANGED', 'local development authentication changed', 'app_session', 409)
+  }
+
+  const register = (token) => portalJSON('/portal/user/app-workspace/' + encodeURIComponent(appID) + '/local-development', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ entry_url: entryURL, manifest }),
+  }, 'app_registration', token)
+
+  const refresh = async (force = false, generation = state.authGeneration) => {
+    assertAuthentication(generation)
+    if (state.refresh) return state.refresh
+    const refreshToken = state.portalToken
+    const previous = force ? state.session : null
+    const pending = portalJSON('/portal/user/apps/' + encodeURIComponent(appID) + '/sessions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ version, runtime_protocol: legacyBridge ? 1 : 2 }),
+    }, 'app_session', refreshToken).then(async (raw) => {
+      if (!raw || typeof raw.access_token !== 'string' || typeof raw.gateway_url !== 'string') throw relayError('APP_SESSION_INVALID', 'platform returned an invalid App Session', 'app_session', 502)
+      const next = { ...raw, gateway_url: normalizeGatewayURL(raw.gateway_url) }
+      if (state.closed || state.authGeneration !== generation || state.portalToken !== refreshToken) {
+        await revoke(next, refreshToken)
+        assertAuthentication(generation)
+        throw relayError('APP_AUTH_CHANGED', 'local development authentication changed', 'app_session', 409)
+      }
+      state.session = next
+      if (previous && previous.session_id !== next.session_id) await revoke(previous, refreshToken)
+      return next
+    }).finally(() => {
+      if (state.refresh === pending) state.refresh = null
+    })
+    state.refresh = pending
+    return pending
+  }
+
+  const loginDetails = () => {
+    if (!state.authState || Date.now() - state.authStateIssuedAt > 10 * 60 * 1000) {
+      state.authState = randomUUID()
+      state.authStateIssuedAt = Date.now()
+    }
+    const query = new URLSearchParams({ proxy_app_auth: '1', proxy_app_state: state.authState, proxy_app_relay: relayURL })
+    return { login_url: portalOrigin + '/#/login?' + query, auth_state: state.authState, relay_url: relayURL }
+  }
+
+  const requireLogin = (response, reason) => jsonResponse(response, 401, {
+    code: 'APP_LOGIN_REQUIRED',
+    error: {
+      code: 'APP_LOGIN_REQUIRED',
+      message: reason ? visibleErrorMessage(reason) + ' 请重新登录后继续。' : '请登录平台账户后继续',
+    },
+    ...loginDetails(),
+  })
+
+  const callbackHTML = (stateValue, type, error) => {
+    const origin = new URL(entryURL).origin
+    const isSuccess = type === 'login-complete'
+    const message = isSuccess
+      ? { protocol: 'proxy-app/auth/v1', type, state: stateValue }
+      : {
+          protocol: 'proxy-app/auth/v1',
+          type: 'login-failed',
+          state: stateValue,
+          error: {
+            code: error?.code || 'APP_LOGIN_FAILED',
+            message: visibleErrorMessage(error),
+            stage: error?.stage || 'login',
+            status: error?.statusCode,
+            request_id: error?.requestId || undefined,
+            upstream_code: error?.upstreamCode || undefined,
+          },
+        }
+    const title = isSuccess ? '登录成功，正在返回应用...' : visibleErrorMessage(error)
+    return '<!doctype html><meta charset="utf-8"><title>平台登录</title><meta name="viewport" content="width=device-width,initial-scale=1"><p>' + htmlEscape(title) + '</p><script>const m=' + safeScriptJSON(message) + ';if(window.opener){window.opener.postMessage(m,' + safeScriptJSON(origin) + ');setTimeout(()=>window.close(),120)}</script>'
+  }
+
+  const forward = (target, request, rawBody, token, appVersion) => {
+    const headers = copyRequestHeaders(request)
+    if (token) headers.set('Authorization', 'Bearer ' + token)
+    if (appVersion) headers.set('X-App-Version', appVersion)
+    return fetch(target, {
+      method: request.method,
+      headers,
+      body: ['GET', 'HEAD'].includes(request.method || '') ? undefined : rawBody,
+      redirect: 'manual',
+    })
+  }
+
+  const close = async () => {
+    if (state.closed) return
+    state.closed = true
+    await state.refresh?.catch(() => undefined)
+    await state.login?.catch(() => undefined)
+    const current = state.session
+    state.session = null
+    await revoke(current)
+    if (server?.listening) await new Promise((resolve) => server.close(resolve))
+  }
+
+  try {
+    server = createServer(async (request, response) => {
+      try {
+        if (state.closed) throw new Error('local development relay is closed')
+        const parsed = new URL(request.url || '/', 'http://127.0.0.1')
+        const runtimePrefix = '/api/app-runtime/v1'
+        const authPath = parsed.pathname.startsWith(runtimePrefix + '/auth/') ? parsed.pathname.slice(runtimePrefix.length) : parsed.pathname
+        const callback = authPath === '/auth/callback' && request.method === 'POST'
+        if (!callback && request.headers['x-proxy-app-relay'] !== relaySecret) {
+          jsonResponse(response, 403, { code: 'LOCAL_DEV_RELAY_UNAUTHORIZED', error: 'local development relay authentication failed' })
+          return
+        }
+        const rawBody = await readBody(request)
+        if (callback) {
+          const form = new URLSearchParams(rawBody.toString('utf8'))
+          const receivedState = form.get('state') || ''
+          const valid = receivedState && receivedState === state.authState && Date.now() - state.authStateIssuedAt <= 10 * 60 * 1000
+          response.setHeader('Content-Type', 'text/html; charset=utf-8')
+          response.setHeader('Cache-Control', 'no-store')
+          if (!valid) {
+            response.statusCode = 400
+            response.end(callbackHTML(receivedState, 'login-failed', relayError('APP_LOGIN_STATE_INVALID', 'login request expired', 'state_validation', 400)))
+            return
+          }
+          state.authState = ''
+          state.authStateIssuedAt = 0
+          const previous = state.session
+          const previousToken = state.portalToken
+          const generation = ++state.authGeneration
+          const token = String(form.get('access_token') || '').trim()
+          state.session = null
+          state.portalToken = token
+          state.refresh = null
+          const pending = (async () => {
+            await revoke(previous, previousToken)
+            assertAuthentication(generation)
+            if (!token) throw relayError('APP_LOGIN_TOKEN_INVALID', 'platform returned an invalid user session token', 'token_validation', 400)
+            await register(token)
+            assertAuthentication(generation)
+            return refresh(true, generation)
+          })()
+          state.login = pending
+          try {
+            await pending
+            assertAuthentication(generation)
+            response.end(callbackHTML(receivedState, 'login-complete'))
+          } catch (error) {
+            if (state.authGeneration === generation) await clearAuthentication()
+            response.statusCode = error?.statusCode || 502
+            response.end(callbackHTML(receivedState, 'login-failed', error))
+          } finally {
+            if (state.login === pending) state.login = null
+          }
+          return
+        }
+        if (parsed.pathname === '/health') { jsonResponse(response, 200, { ok: true, app_id: appID, app_slug: appSlug, app_version: version, runtime_protocol: legacyBridge ? 1 : 2, authenticated: Boolean(state.session) }); return }
+        if (authPath === '/auth/start') { jsonResponse(response, 200, { data: { authenticated: Boolean(state.session), ...loginDetails() } }); return }
+        if (authPath === '/auth/logout' && request.method === 'POST') {
+          await clearAuthentication()
+          jsonResponse(response, 200, { data: { success: true } })
+          return
+        }
+        if (authPath === '/auth/status') { jsonResponse(response, 200, { data: { authenticated: Boolean(state.session), app_id: appID, app_version: version } }); return }
+        if (parsed.pathname === '/bridge') {
+          if (!legacyBridge) {
+            jsonResponse(response, 404, { error: { code: 'APP_LEGACY_BRIDGE_DISABLED', message: 'Legacy Bridge is disabled; use the HTTP runtime or start proxy-app dev with --legacy-bridge for an old application.' } })
+            return
+          }
+          if (!state.session) { requireLogin(response); return }
+          let bridgeRequest
+          try { bridgeRequest = JSON.parse(rawBody.toString('utf8') || '{}') } catch { jsonResponse(response, 400, { code: 'APP_BRIDGE_INVALID_REQUEST', error: 'invalid bridge request' }); return }
+          bridgeRequest.appId = appSlug
+          const generation = state.authGeneration
+          const upstream = await forward(portal + '/portal/user/apps/' + encodeURIComponent(appID) + '/bridge', request, Buffer.from(JSON.stringify(bridgeRequest)), state.portalToken)
+          if (state.authGeneration !== generation) {
+            await upstream.body?.cancel().catch(() => undefined)
+            assertAuthentication(generation)
+          }
+          if (upstream.status === 401) {
+            await clearAuthentication()
+            requireLogin(response, relayError('APP_LOGIN_SESSION_EXPIRED', 'platform user session expired', 'bridge', 401))
+            return
+          }
+          response.statusCode = upstream.status
+          copyResponseHeaders(upstream, response)
+          if (upstream.body) Readable.fromWeb(upstream.body).pipe(response); else response.end()
+          return
+        }
+        const runtimeRequest = parsed.pathname === runtimePrefix || parsed.pathname.startsWith(runtimePrefix + '/')
+        const gatewayRequest = parsed.pathname === '/v1' || parsed.pathname.startsWith('/v1/')
+        if (runtimeRequest || gatewayRequest) {
+          if (!state.session) { requireLogin(response); return }
+          const prefix = runtimeRequest ? runtimePrefix : '/v1'
+          const suffix = parsed.pathname.slice(prefix.length) || '/'
+          const target = (session) => (runtimeRequest ? portal + '/app-runtime/v1' : session.gateway_url) + suffix + parsed.search
+          const generation = state.authGeneration
+          let current = state.session
+          let upstream = await forward(target(current), request, rawBody, current.access_token, current.app_version)
+          if (await retryableSessionExpiry(upstream, runtimeRequest)) {
+            await upstream.arrayBuffer().catch(() => undefined)
+            try {
+              assertAuthentication(generation)
+              current = state.session && state.session.access_token !== current.access_token ? state.session : await refresh(true, generation)
+            } catch (error) {
+              assertAuthentication(generation)
+              if (error?.code === 'APP_LOGIN_SESSION_EXPIRED' || error?.code === 'APP_LOGIN_NOT_ALLOWED') {
+                await clearAuthentication()
+                requireLogin(response, error)
+                return
+              }
+              throw error
+            }
+            assertAuthentication(generation)
+            upstream = await forward(target(current), request, rawBody, current.access_token, current.app_version)
+          }
+          if (state.authGeneration !== generation) {
+            await upstream.body?.cancel().catch(() => undefined)
+            assertAuthentication(generation)
+          }
+          response.statusCode = upstream.status
+          copyResponseHeaders(upstream, response)
+          if (upstream.body) Readable.fromWeb(upstream.body).pipe(response); else response.end()
+          return
+        }
+        jsonResponse(response, 404, { code: 'LOCAL_DEV_ROUTE_NOT_FOUND', error: 'local development route not found' })
+      } catch (error) {
+        jsonResponse(response, error?.statusCode || (error?.message === 'local development relay is closed' ? 503 : 502), { code: error?.code || 'LOCAL_DEV_RELAY_ERROR', error: error instanceof Error ? error.message : String(error) })
+      }
+    })
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve) })
+    const address = server.address()
+    relayURL = 'http://127.0.0.1:' + address.port
+    return { relayURL, close }
+  } catch (error) {
+    await close()
+    throw error
+  }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ducking-mind/proxy-app-cli",
+  "version": "0.1.0",
+  "description": "CLI for creating, building and publishing Proxy platform apps",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/duckingmind/app.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/duckingmind/app/tree/main/cli#readme",
+  "bugs": {
+    "url": "https://github.com/duckingmind/app/issues"
+  },
+  "type": "module",
+  "bin": {
+    "proxy-app": "./proxy-app.mjs"
+  },
+  "files": [
+    "proxy-app.mjs",
+    "local-dev-relay.mjs"
+  ],
+  "scripts": {
+    "test": "node --check proxy-app.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fflate": "^0.8.2"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "license": "MIT"
+}

package/proxy-app.mjs

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises'
+import { createHash, randomUUID } from 'node:crypto'
+import { dirname, join, resolve, sep } from 'node:path'
+import { zipSync } from 'fflate'
+import { createLocalDevelopmentRelay } from './local-dev-relay.mjs'
+
+const MAX_BUNDLE_BYTES = 50 * 1024 * 1024
+const ALLOWED_PERMISSIONS = new Set(['user.profile.read', 'storage.user', 'notification', 'theme.read', 'locale.read'])
+const ALLOWED_APIS = new Set(['model.responses', 'model.chat', 'model.messages', 'model.embeddings', 'model.images', 'model.videos', 'model.music'])
+const ALLOWED_PRICING_MODES = new Set(['free', 'one_time', 'commission'])
+const ALLOWED_CATEGORIES = new Set(['productivity', 'creative', 'developer', 'data', 'communication', 'education', 'finance', 'other'])
+const BUNDLE_IGNORED_FILES = new Set(['.proxy-app.json'])
+const APP_WORKSPACE_PATH = '/portal/user/app-workspace'
+
+function usage() {
+  console.log(`Usage:
+  proxy-app init <app-dir> [--name <name>]
+  proxy-app create <app-dir> [--category productivity] [--description text]
+  proxy-app link <app-dir> <app-id>
+  proxy-app status <app-dir>
+  proxy-app doctor <app-dir>
+  proxy-app dev <app-dir> [--port <port>] [--legacy-bridge]
+  proxy-app validate <app-dir>
+  proxy-app build <app-dir>
+  proxy-app pack <app-dir> [output.zip]
+  proxy-app upload <app-dir> [output.zip]
+  proxy-app publish <app-dir> [output.zip]
+
+  Add --source to pack/upload only for local debugging; release packages require dist.
+  Categories: productivity, creative, developer, data, communication, education, finance, other.
+
+Publish environment:
+  PROXY_API_BASE_URL  default: http://localhost:9003/api
+  PROXY_USER_ACCESS_TOKEN  Current platform user session for app management/CI only; never passed to the app
+  PROXY_ACCESS_TOKEN       Legacy alias for PROXY_USER_ACCESS_TOKEN
+
+  Local development:
+  proxy-app dev <app-dir> [--port 5173]
+  Starts a real platform relay. The app opens platform login on first use;
+  requests then use the signed-in user's App Session, models, routing, quota
+  and billing. No separate developer identity or runtime credential exists.
+  HTTP APIs are the default. --legacy-bridge enables v1 Bridge compatibility.
+
+Platform verification:
+  Build and pack the app, upload the ZIP, then publish the selected version.
+`)
+}
+
+function option(args, name, fallback = '') {
+  const index = args.indexOf(name)
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback
+}
+
+function outputArgument(args) {
+  return args.slice(1).find((arg) => arg !== '--source') || undefined
+}
+
+function apiSettings() {
+  const token = process.env.PROXY_USER_ACCESS_TOKEN || process.env.PROXY_ACCESS_TOKEN
+  const baseURL = (process.env.PROXY_API_BASE_URL || 'http://localhost:9003/api').replace(/\/$/, '')
+  if (!token) throw new Error('PROXY_USER_ACCESS_TOKEN is required for app management commands; it is never passed to the app runtime')
+  return { token, baseURL }
+}
+
+function responseError(body, fallback) {
+  const message = typeof body?.error === 'string' ? body.error : body?.error?.message || body?.message
+  const code = body?.code || body?.error?.code
+  return `${message || fallback}${code ? ` (${code})` : ''}`
+}
+
+async function apiJSON(path, init = {}) {
+  const { token, baseURL } = apiSettings()
+  const response = await fetch(`${baseURL}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, ...(init.headers || {}) } })
+  const body = await response.json().catch(() => ({}))
+  if (!response.ok) {
+    const message = typeof body.error === 'string' ? body.error : body.error?.message || body.message
+    const code = body.code || body.error?.code
+    throw new Error(`${message || `request failed: HTTP ${response.status}`}${code ? ` (${code})` : ''}`)
+  }
+  return body.data || body
+}
+
+function safeRelative(value) {
+  const normalized = String(value || '').replaceAll('\\', '/')
+  if (!normalized || normalized.startsWith('/') || normalized.includes('\0')) throw new Error(`invalid relative path: ${value}`)
+  if (normalized.split('/').some((part) => part === '..')) throw new Error(`path traversal is not allowed: ${value}`)
+  return normalized.split('/').filter(Boolean).join('/')
+}
+
+async function exists(path) {
+  try {
+    await stat(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function readManifest(appDir) {
+  let manifest
+  try {
+    manifest = JSON.parse(await readFile(join(appDir, 'manifest.json'), 'utf8'))
+  } catch (error) {
+    throw new Error(`manifest.json is missing or invalid: ${error.message}`)
+  }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) throw new Error('manifest must be a JSON object')
+  if (manifest.schema !== 'proxy.app/v1') throw new Error('manifest.schema must be proxy.app/v1')
+  if (!/^[a-z0-9]+(?:[.-][a-z0-9]+)+(?:[.-][a-z0-9]+)*$/.test(manifest.id || '')) throw new Error('manifest.id is invalid')
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(manifest.version || '')) throw new Error('manifest.version is invalid')
+  if (typeof manifest.name !== 'string' || !manifest.name.trim()) throw new Error('manifest.name is required')
+  if (manifest.runtime?.type !== 'iframe') throw new Error('manifest.runtime.type must be iframe')
+  if (manifest.backend?.type !== 'platform') throw new Error('manifest.backend.type must be platform')
+  if (!Array.isArray(manifest.permissions)) throw new Error('manifest.permissions must be an array')
+  const permissions = new Set()
+  for (const permission of manifest.permissions) {
+    if (!ALLOWED_PERMISSIONS.has(permission)) throw new Error(`unsupported app permission: ${permission}`)
+    if (permissions.has(permission)) throw new Error(`duplicate app permission: ${permission}`)
+    permissions.add(permission)
+  }
+  if (manifest.apis !== undefined && !Array.isArray(manifest.apis)) throw new Error('manifest.apis must be an array')
+  const apis = new Set()
+  for (const api of manifest.apis || []) {
+    if (!ALLOWED_APIS.has(api)) throw new Error(`unsupported app API: ${api}`)
+    if (apis.has(api)) throw new Error(`duplicate app API: ${api}`)
+    apis.add(api)
+  }
+  if (manifest.pricing !== undefined && (!manifest.pricing || typeof manifest.pricing !== 'object' || Array.isArray(manifest.pricing))) {
+    throw new Error('manifest.pricing must be an object')
+  }
+  const pricing = manifest.pricing || { mode: 'free', currency: 'CNY' }
+  const mode = pricing.mode || 'free'
+  const oneTimePrice = pricing.one_time_price || 0
+  const commissionRate = pricing.commission_rate || 0
+  if (!ALLOWED_PRICING_MODES.has(mode)) throw new Error('manifest.pricing.mode must be free, one_time, or commission')
+  if (!/^[A-Z]{3,10}$/.test(pricing.currency || 'CNY')) throw new Error('manifest.pricing.currency is invalid')
+  if (!Number.isFinite(oneTimePrice) || !Number.isFinite(commissionRate) || oneTimePrice < 0 || commissionRate < 0) throw new Error('manifest.pricing values must be non-negative numbers')
+  if (mode === 'free' && (oneTimePrice !== 0 || commissionRate !== 0)) throw new Error('free pricing requires zero one_time_price and commission_rate')
+  if (mode === 'one_time' && (oneTimePrice <= 0 || commissionRate !== 0)) throw new Error('one_time pricing requires positive one_time_price and zero commission_rate')
+  if (mode === 'commission' && (commissionRate <= 0 || commissionRate > 100 || oneTimePrice !== 0)) throw new Error('commission pricing requires commission_rate between 0 and 100 and zero one_time_price')
+  const entry = safeRelative(manifest.runtime.entry)
+  return { manifest, entry }
+}
+
+async function validateApp(appDir) {
+  const root = resolve(appDir)
+  const { manifest, entry } = await readManifest(root)
+  const artifactRoot = (await exists(join(root, 'dist'))) ? join(root, 'dist') : root
+  if (!(await exists(join(artifactRoot, entry)))) throw new Error(`runtime entry is missing: ${entry}`)
+  if (artifactRoot !== root && /(?:src|href)=["']\//i.test(await readFile(join(artifactRoot, entry), 'utf8'))) {
+    throw new Error("built entry contains root-relative assets; configure the bundler to emit relative URLs (Vite: base: './')")
+  }
+  if (manifest.assets?.icon && !(await exists(join(artifactRoot, safeRelative(manifest.assets.icon))))) {
+    console.warn(`warning: manifest.assets.icon is missing: ${manifest.assets.icon}`)
+  }
+  return { root, artifactRoot, manifest, entry }
+}
+
+function run(command, args, cwd) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' })
+    child.on('error', reject)
+    child.on('exit', (code, signal) => code === 0 ? resolvePromise() : reject(new Error(`${command} exited with ${code ?? signal}`)))
+  })
+}
+
+function runChild(command, args, cwd, env) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: 'inherit', shell: process.platform === 'win32' })
+    const stop = () => child.kill('SIGTERM')
+    process.once('SIGINT', stop)
+    process.once('SIGTERM', stop)
+    child.on('error', reject)
+    child.on('exit', (code, signal) => {
+      process.removeListener('SIGINT', stop)
+      process.removeListener('SIGTERM', stop)
+      if (code === 0 || signal === 'SIGINT' || signal === 'SIGTERM') resolvePromise()
+      else reject(new Error(`${command} exited with ${code ?? signal}`))
+    })
+  })
+}
+
+async function devApp(appDir, args) {
+  const root = resolve(appDir)
+  const { manifest } = await readManifest(root)
+  const supportedOptions = new Set(['--port', '--legacy-bridge'])
+  for (const arg of args) {
+    if (arg.startsWith('--') && !supportedOptions.has(arg)) {
+      throw new Error(`unsupported dev option: ${arg}; local development always uses the real platform`)
+    }
+  }
+  const binding = await projectBinding(root)
+  if (binding.slug !== manifest.id) throw new Error('应用标识与本地绑定不一致，请先运行 proxy-app link 或重新创建应用')
+  const requestedPort = option(args, '--port', process.env.PROXY_APP_DEV_PORT || '5173')
+  if (!/^\d+$/.test(requestedPort) || Number(requestedPort) < 1 || Number(requestedPort) > 65535) throw new Error('--port must be between 1 and 65535')
+  const entryURL = process.env.PROXY_APP_DEV_URL || `http://127.0.0.1:${requestedPort}/`
+  let parsedEntryURL
+  try { parsedEntryURL = new URL(entryURL) } catch { throw new Error('PROXY_APP_DEV_URL must be a valid loopback http(s) URL') }
+  if (!['http:', 'https:'].includes(parsedEntryURL.protocol) || !['localhost', '127.0.0.1', '::1'].includes(parsedEntryURL.hostname) || parsedEntryURL.username || parsedEntryURL.password) {
+    throw new Error('PROXY_APP_DEV_URL must use localhost, 127.0.0.1, or ::1 without credentials')
+  }
+  const relaySecret = randomUUID()
+  const baseURL = (process.env.PROXY_API_BASE_URL || 'http://localhost:9003/api').replace(/\/$/, '')
+  const portalURL = process.env.PROXY_PORTAL_URL || process.env.PROXY_PUBLIC_URL || 'http://localhost:9004'
+  const legacyBridge = args.includes('--legacy-bridge')
+  const relay = await createLocalDevelopmentRelay({
+    baseURL,
+    portalURL,
+    relaySecret,
+    appID: binding.app_id,
+    appSlug: manifest.id,
+    version: manifest.version,
+    manifest,
+    entryURL,
+    legacyBridge,
+  })
+  const {
+    PROXY_USER_ACCESS_TOKEN: _userToken,
+    PROXY_ACCESS_TOKEN: _legacyToken,
+    PROXY_API_BASE_URL: _apiBaseURL,
+    PROXY_PORTAL_URL: _portalURL,
+    PROXY_PUBLIC_URL: _publicURL,
+    PROXY_APP_DEV_URL: _entryURL,
+    PROXY_APP_DEV_PORT: _devPort,
+    PROXY_PLATFORM_GATEWAY_URL: _gatewayURL,
+    PROXY_PLATFORM_RUNTIME_URL: _runtimeURL,
+    PROXY_PLATFORM_BRIDGE_URL: _bridgeURL,
+    PROXY_PLATFORM_AUTH_URL: _authURL,
+    PROXY_PLATFORM_RELAY_SECRET: _inheritedRelaySecret,
+    ...safeChildEnv
+  } = process.env
+  const childEnv = {
+    ...safeChildEnv,
+    PROXY_PLATFORM_GATEWAY_URL: `${relay.relayURL}/v1`,
+    ...(!legacyBridge ? { PROXY_PLATFORM_RUNTIME_URL: `${relay.relayURL}/api/app-runtime/v1` } : { PROXY_PLATFORM_BRIDGE_URL: `${relay.relayURL}/bridge` }),
+    PROXY_PLATFORM_AUTH_URL: `${relay.relayURL}/auth`,
+    PROXY_PLATFORM_RELAY_SECRET: relaySecret,
+  }
+  console.log(`Proxy App platform relay ready: ${relay.relayURL}`)
+  console.log(`Local app: ${entryURL}`)
+  console.log(`Runtime transport: ${legacyBridge ? 'legacy Bridge compatibility' : 'same-origin HTTP (/v1, /api/app-runtime/v1)'}`)
+  console.log('Platform mode: sign in from the app to use real models, provider routing, quota and billing.')
+  try {
+    await runChild('npm', ['run', 'dev', '--', '--host', '127.0.0.1', '--port', requestedPort, '--strictPort'], root, childEnv)
+  } finally {
+    await relay.close()
+  }
+}
+
+async function packApp(appDir, output, { allowSource = false } = {}) {
+  const info = await validateApp(appDir)
+  if (info.artifactRoot === info.root && !allowSource) {
+    throw new Error('build output is missing; run proxy-app build before packing (use --source only for local debugging)')
+  }
+  const outputPath = resolve(output || join(info.root, `${info.manifest.id}-${info.manifest.version}.zip`))
+  const files = {}
+  const collect = async (directory, prefix = '') => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      if (['node_modules', '.git', 'dist'].includes(entry.name) || BUNDLE_IGNORED_FILES.has(entry.name) || entry.name.endsWith('.zip')) continue
+      if (entry.name === '.env' || entry.name.startsWith('.env.') || entry.name === '.npmrc') {
+        throw new Error(`sensitive file cannot be included in app bundle: ${entry.name}`)
+      }
+      if (entry.isSymbolicLink()) throw new Error(`symbolic links are not allowed in app bundles: ${entry.name}`)
+      const absolute = join(directory, entry.name)
+      const archivePath = prefix ? `${prefix}/${entry.name}` : entry.name
+      if (entry.isDirectory()) await collect(absolute, archivePath)
+      else files[archivePath] = new Uint8Array(await readFile(absolute))
+    }
+  }
+  if (info.artifactRoot === info.root) await collect(info.root)
+  else await collect(info.artifactRoot)
+  files['manifest.json'] = new Uint8Array(await readFile(join(info.root, 'manifest.json')))
+  const bundle = zipSync(files, { level: 9 })
+  if (bundle.length > MAX_BUNDLE_BYTES) throw new Error(`bundle is larger than ${MAX_BUNDLE_BYTES} bytes`)
+  await mkdir(dirname(outputPath), { recursive: true })
+  await writeFile(outputPath, bundle)
+  console.log(JSON.stringify({ output: outputPath, id: info.manifest.id, version: info.manifest.version, size: bundle.length, sha256: createHash('sha256').update(bundle).digest('hex') }, null, 2))
+  return { ...info, outputPath }
+}
+
+async function writeProject(root, app) {
+  await mkdir(join(root, 'src'), { recursive: true })
+  await writeFile(join(root, 'manifest.json'), JSON.stringify({ schema: 'proxy.app/v1', id: app.slug, version: '0.1.0', name: app.name, description: app.description || '', runtime: { type: 'iframe', entry: 'index.html' }, permissions: [], apis: [], backend: { type: 'platform' }, pricing: { mode: 'free', currency: 'CNY' } }, null, 2) + '\n')
+  await writeFile(join(root, 'index.html'), '<!doctype html>\n<html lang="zh-CN"><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Proxy App</title></head><body><main id="app"></main><script type="module" src="/src/main.ts"></script></body></html>\n')
+  await writeFile(join(root, 'src', 'main.ts'), `import { createAppClient } from '@ducking-mind/proxy-app-sdk'\n\nconst client = createAppClient(${JSON.stringify(app.slug)}, { localDevelopment: import.meta.env.DEV, localAppVersion: '0.1.0' })\nconst root = document.querySelector<HTMLElement>('#app')\nif (root) root.textContent = ${JSON.stringify(app.name)}\nvoid client.platform.capabilities().then(console.log)\n`)
+  await writeFile(join(root, 'vite.config.ts'), "import { defineConfig } from 'vite'\nimport { createPlatformDevProxy } from '@ducking-mind/proxy-app-sdk/vite'\n\nexport default defineConfig({\n  base: './',\n  server: {\n    host: '127.0.0.1',\n    proxy: createPlatformDevProxy(),\n  },\n})\n")
+  await writeFile(join(root, 'tsconfig.json'), JSON.stringify({ compilerOptions: { target: 'ES2020', module: 'ESNext', moduleResolution: 'Bundler', strict: true, lib: ['ES2020', 'DOM'], types: ['vite/client'], noEmit: true }, include: ['src', 'vite.config.ts'] }, null, 2) + '\n')
+  await writeFile(join(root, 'package.json'), JSON.stringify({ name: app.slug.replaceAll('.', '-'), private: true, type: 'module', scripts: { dev: 'vite', typecheck: 'tsc --noEmit', build: 'npm run typecheck && vite build' }, dependencies: { '@ducking-mind/proxy-app-sdk': '^0.1.0' }, devDependencies: { typescript: '^5.2.2', vite: '^8.2.2' } }, null, 2) + '\n')
+}
+
+async function replaceIdentifier(root, previous, next) {
+  const sourceRoot = join(root, 'src')
+  if (!(await exists(sourceRoot))) return
+  const walk = async (directory) => {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const target = join(directory, entry.name)
+      if (entry.isDirectory()) await walk(target)
+      else if (/\.(?:js|jsx|ts|tsx)$/.test(entry.name)) {
+        const source = await readFile(target, 'utf8')
+        if (source.includes(previous)) await writeFile(target, source.replaceAll(previous, next))
+      }
+    }
+  }
+  await walk(sourceRoot)
+}
+
+async function initApp(appDir, args) {
+  const root = resolve(appDir)
+  if (await exists(root) && (await exists(join(root, 'manifest.json')) || await exists(join(root, 'package.json')))) {
+    throw new Error(`directory already contains an app: ${root}`)
+  }
+  const name = option(args, '--name', root.split(sep).pop() || 'Proxy App')
+  const app = { id: '', slug: `app.proxy.local.${randomUUID().replaceAll('-', '').slice(0, 16)}`, name, description: '' }
+  await writeProject(root, app)
+  console.log(JSON.stringify({ created: root, local_identifier: app.slug, next: [`cd ${root}`, 'npm install', `proxy-app create ${root}`, `proxy-app dev ${root}`, 'npm run build'] }, null, 2))
+}
+
+async function createApp(appDir, args) {
+  const root = resolve(appDir)
+  if (await exists(join(root, '.proxy-app.json'))) throw new Error('app is already linked; run proxy-app status to inspect it')
+  const { manifest } = await readManifest(root)
+  const localIdentifier = manifest.id
+  const name = option(args, '--name', manifest.name || root.split(sep).pop() || 'Proxy App')
+  const category = option(args, '--category', 'productivity')
+  if (!ALLOWED_CATEGORIES.has(category)) throw new Error(`unsupported app category: ${category}`)
+  const app = await apiJSON(APP_WORKSPACE_PATH, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name, description: option(args, '--description', manifest.description || ''), category }) })
+  if (!app || typeof app.id !== 'string' || typeof app.slug !== 'string' || !/^[a-z0-9]+(?:[.-][a-z0-9]+)+(?:[.-][a-z0-9]+)*$/.test(app.slug)) {
+    throw new Error('platform returned an invalid app binding; expected id and lowercase reverse-domain slug')
+  }
+  manifest.id = app.slug
+  await writeFile(join(root, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
+  await replaceIdentifier(root, localIdentifier, app.slug)
+  await writeFile(join(root, '.proxy-app.json'), JSON.stringify({ app_id: app.id, slug: app.slug }, null, 2) + '\n')
+  console.log(JSON.stringify({ created: root, app_id: app.id, app_identifier: app.slug, next: [`proxy-app upload ${root}`] }, null, 2))
+}
+
+async function linkApp(appDir, appID) {
+  const root = resolve(appDir)
+  const result = await apiJSON(APP_WORKSPACE_PATH)
+  const app = (result.items || []).find((item) => item.id === appID)
+  if (!app) throw new Error(`application not found: ${appID}`)
+  const manifestPath = join(root, 'manifest.json')
+  const { manifest } = await readManifest(root)
+  if (typeof app.slug !== 'string' || !/^[a-z0-9]+(?:[.-][a-z0-9]+)+(?:[.-][a-z0-9]+)*$/.test(app.slug)) {
+    throw new Error(`application has an invalid identifier: ${app.slug || '(missing)'}`)
+  }
+  const previous = manifest.id
+  manifest.id = app.slug
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+  await replaceIdentifier(root, previous, app.slug)
+  await writeFile(join(root, '.proxy-app.json'), JSON.stringify({ app_id: app.id, slug: app.slug }, null, 2) + '\n')
+  console.log(JSON.stringify({ linked: root, app_id: app.id, app_identifier: app.slug }, null, 2))
+}
+
+async function projectBinding(appDir) {
+  try {
+    const config = JSON.parse(await readFile(join(resolve(appDir), '.proxy-app.json'), 'utf8'))
+    if (typeof config.app_id === 'string' && config.app_id && typeof config.slug === 'string' && /^[a-z0-9]+(?:[.-][a-z0-9]+)+(?:[.-][a-z0-9]+)*$/.test(config.slug)) return config
+  } catch {}
+  throw new Error('app binding is missing or invalid; run proxy-app create or proxy-app link first')
+}
+
+async function projectAppID(appDir) {
+  return (await projectBinding(appDir)).app_id
+}
+
+async function developerApp(appDir) {
+  const appID = await projectAppID(appDir)
+  const result = await apiJSON(APP_WORKSPACE_PATH)
+  const app = (result.items || []).find((item) => item.id === appID)
+  if (!app) throw new Error(`linked application was not found: ${appID}`)
+  return app
+}
+
+async function submitAppVersion(appID, manifest) {
+  const { token, baseURL } = apiSettings()
+  const submit = await fetch(`${baseURL}${APP_WORKSPACE_PATH}/${encodeURIComponent(appID)}/versions/${encodeURIComponent(manifest.version)}/submit`, { method: 'POST', headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ pricing_mode: manifest.pricing?.mode || 'free', one_time_price: manifest.pricing?.one_time_price || 0, commission_rate: manifest.pricing?.commission_rate || 0, currency: manifest.pricing?.currency || 'CNY' }) })
+  const submitBody = await submit.json().catch(() => ({}))
+  if (!submit.ok) throw new Error(responseError(submitBody, `submit failed: HTTP ${submit.status}`))
+  return submitBody.data || submitBody
+}
+
+async function uploadApp(appDir, output, options = {}) {
+  const binding = await projectBinding(appDir)
+  const { token, baseURL } = apiSettings()
+  const bundleInfo = await packApp(appDir, output, options)
+  if (binding.slug !== bundleInfo.manifest.id) {
+    throw new Error('应用标识不匹配，请先同步当前应用绑定，再重新 build 和 pack。')
+  }
+  const bundle = await readFile(bundleInfo.outputPath)
+  const form = new FormData(); form.append('file', new Blob([bundle], { type: 'application/zip' }), `${bundleInfo.manifest.id}-${bundleInfo.manifest.version}.zip`)
+  const response = await fetch(`${baseURL}${APP_WORKSPACE_PATH}/${encodeURIComponent(binding.app_id)}/versions`, { method: 'POST', headers: { Authorization: `Bearer ${token}` }, body: form })
+  const body = await response.json().catch(() => ({})); if (!response.ok) throw new Error(responseError(body, `upload failed: HTTP ${response.status}`))
+  console.log(JSON.stringify({ uploaded: body.data || body, next: `proxy-app publish ${appDir}` }, null, 2))
+  return body.data || body
+}
+
+async function publishApp(appDir, output) {
+  const info = await validateApp(appDir)
+  const remoteApp = await developerApp(appDir)
+  if (remoteApp.slug !== info.manifest.id) {
+    throw new Error('应用标识不匹配，请先同步当前应用绑定，再重新 build 和 pack。')
+  }
+  let version = (remoteApp.versions || []).find((item) => item.version === info.manifest.version)
+  let uploaded = null
+  if (!version) {
+    uploaded = await uploadApp(appDir, output)
+    version = uploaded
+  }
+  if (['review', 'published'].includes(version.review_status)) {
+    console.log(JSON.stringify({ submitted: false, reason: `version is already ${version.review_status}`, app_id: remoteApp.id, version: info.manifest.version }, null, 2))
+    return
+  }
+  if (!['draft', 'rejected'].includes(version.review_status)) throw new Error(`version cannot be submitted from status: ${version.review_status || 'unknown'}`)
+  const submitted = await submitAppVersion(remoteApp.id, info.manifest)
+  console.log(JSON.stringify({ uploaded, submitted, app_id: remoteApp.id, version: info.manifest.version }, null, 2))
+}
+
+async function statusApp(appDir) {
+  const root = resolve(appDir)
+  const { manifest } = await readManifest(root)
+  let binding = null
+  try { binding = JSON.parse(await readFile(join(root, '.proxy-app.json'), 'utf8')) } catch {}
+  if (!binding?.app_id) {
+    console.log(JSON.stringify({ linked: false, local_identifier: manifest.id, version: manifest.version, next: `proxy-app create ${appDir}` }, null, 2))
+    return
+  }
+  const app = await developerApp(root)
+  const version = (app.versions || []).find((item) => item.version === manifest.version)
+  console.log(JSON.stringify({ linked: true, app_id: app.id, app_identifier: app.slug, app_status: app.status, local_version: manifest.version, remote_version: version || null }, null, 2))
+}
+
+async function doctorApp(appDir) {
+  const root = resolve(appDir)
+  const checks = []
+  const major = Number(process.versions.node.split('.')[0])
+  checks.push({ name: 'node', ok: major >= 20, detail: process.version })
+  try {
+    const info = await validateApp(root)
+    checks.push({ name: 'manifest', ok: true, detail: `${info.manifest.id}@${info.manifest.version}` })
+    checks.push({ name: 'build', ok: info.artifactRoot !== info.root, detail: info.artifactRoot !== info.root ? 'dist found' : 'dist not found; run proxy-app build' })
+  } catch (error) {
+    checks.push({ name: 'manifest', ok: false, detail: error.message })
+  }
+  try {
+    const config = JSON.parse(await readFile(join(root, '.proxy-app.json'), 'utf8'))
+    checks.push({ name: 'binding', ok: Boolean(config.app_id && config.slug), detail: config.app_id || 'invalid .proxy-app.json' })
+  } catch {
+    checks.push({ name: 'binding', ok: false, detail: 'not linked; create or link before upload' })
+  }
+  const valid = checks.every((item) => item.ok)
+  console.log(JSON.stringify({ ok: valid, ready_for_upload: valid, checks }, null, 2))
+  if (!valid) process.exitCode = 1
+}
+
+const [, , command, ...args] = process.argv
+try {
+  if (!command || command === '--help' || command === '-h') usage()
+  else if (command === 'dev') await devApp(args[0] || '.', args.slice(1))
+  else if (command === 'init') await initApp(args[0] || '.', args.slice(1))
+  else if (command === 'create') {
+    if (!args[0]) throw new Error('create requires <app-dir>')
+    await createApp(args[0], args.slice(1))
+  }
+  else if (command === 'link') {
+    if (!args[1]) throw new Error('link requires <app-dir> <app-id>')
+    await linkApp(args[0], args[1])
+  }
+  else if (command === 'status') await statusApp(args[0] || '.')
+  else if (command === 'doctor') await doctorApp(args[0] || '.')
+  else if (command === 'validate') {
+    const info = await validateApp(args[0] || '.')
+    console.log(JSON.stringify({ valid: true, id: info.manifest.id, version: info.manifest.version, entry: info.entry }, null, 2))
+  } else if (command === 'build') {
+    await run('npm', ['run', 'build'], resolve(args[0] || '.'))
+    await validateApp(args[0] || '.')
+  } else if (command === 'pack') await packApp(args[0] || '.', outputArgument(args), { allowSource: args.includes('--source') })
+  else if (command === 'upload') {
+    if (!args[0]) throw new Error('upload requires <app-dir>')
+    await uploadApp(args[0], outputArgument(args), { allowSource: args.includes('--source') })
+  }
+  else if (command === 'publish') {
+    if (!args[0]) throw new Error('publish requires <app-dir>')
+    await publishApp(args[0], args[1])
+  } else {
+    usage()
+    throw new Error(`unknown command: ${command}`)
+  }
+} catch (error) {
+  console.error(`proxy app: ${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}