@heybox/hb-sdk 0.4.4 → 0.4.6

package/skill/scripts/sync-references.mjs

@@ -203,9 +203,50 @@ const cliDevSection = [
   extractSection(cliGuide, '## Mock runtime 边界'),
 ].filter(Boolean).join('\n\n');
 const cliDeploySection = extractSection(cliGuide, '## 部署发布');
+const cliRemoteSection = extractSection(cliGuide, '## 远端管理命令');
 const cliLoginSection = extractSection(cliGuide, '## CLI 登录态');
 const cliDoctorSection = extractSection(cliGuide, '## Agent Skill doctor');
 const cliUpdateSection = extractSection(cliGuide, '## 版本提醒');
+const cliCommandSurface = `hb-sdk create <project-name>
+hb-sdk dev [--port <port>] [--mock-port <port>] [--runtime-url <url>] [--no-open]
+hb-sdk login [--login-base-url <url>] [--no-select-entity]
+hb-sdk login status
+hb-sdk login clear
+hb-sdk doctor
+hb-sdk remote access
+hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>
+hb-sdk remote list [--status <status>] [--keyword <text>]
+hb-sdk remote create --name <name> [--preview-image-url <url>] [--yes] [--force-bind]
+hb-sdk remote bind <mini-program-id> [--force]
+hb-sdk remote info
+hb-sdk remote update [--name <name>] [--preview-image-url <url>]
+hb-sdk remote allowlist list
+hb-sdk remote allowlist add <heybox-id...>
+hb-sdk remote allowlist remove <heybox-id...>
+hb-sdk remote allowlist set <heybox-id...>
+hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]
+hb-sdk remote versions
+hb-sdk remote preview <version>
+hb-sdk remote release <version> [--yes]
+hb-sdk remote withdraw <version> [--yes] [--reason <text>]
+hb-sdk remote take-down [--yes]
+hb-sdk remote reopen [--yes]
+
+Removed: hb-sdk deploy`;
+
+const cliRemoteEntitySection = `Developer entity selection lives under \`hb-sdk remote entity\`:
+
+${fenced('bash', `hb-sdk remote entity list
+hb-sdk remote entity current
+hb-sdk remote entity switch <entity-id>`)}
+
+The authoritative current entity is the developer platform server-side current entity. The CLI auth cache may contain a \`selectedEntity\` value, but that value is only a hint snapshot for \`hb-sdk login status\` display and drift troubleshooting. Do not use \`selectedEntity\` as the source of truth for permissions, ownership, create, bind, deploy, or release decisions.
+
+\`hb-sdk login\` tries to make the server-side current entity explicit after browser login. Zero entities leaves login successful and prints a guidance message. One entity is displayed and, when needed, switched to current. Multiple entities in a TTY prompt for a choice; multiple entities in non-interactive mode do not block login but tell the user to run \`hb-sdk remote entity switch <entity-id>\`. Passing \`--no-select-entity\` writes only the login state and does not modify the server-side current entity.`;
+
+const cliRemoteEntityDeploySection = `Before precheck, build, upload, or submit audit, \`hb-sdk remote deploy\` must verify that the current project's bound mini-program belongs to the server-side current entity. If \`detail.entity_id\` differs from the current entity, the command fails with both entity ids/names and suggests \`hb-sdk remote entity switch <entity-id>\`. It must not auto-switch entities and must not continue into precheck/build/upload/submit on mismatch.`;
 
 const files = new Map();
 
@@ -296,6 +337,8 @@ files.set('cli.md', `${header('CLI reference', [
   ['Create a mini-program template', 'create-a-mini-program-template'],
   ['Local dev and mock runtime', 'local-dev-and-mock-runtime'],
   ['Deploy and backend operations', 'deploy-and-backend-operations'],
+  ['Remote entity scope', 'remote-entity-scope'],
+  ['Remote management commands', 'remote-management-commands'],
   ['CLI login cache', 'cli-login-cache'],
   ['Agent Skill doctor', 'agent-skill-doctor'],
   ['Update reminders', 'update-reminders'],
@@ -303,7 +346,7 @@ files.set('cli.md', `${header('CLI reference', [
   ['Generated template README', 'generated-template-readme'],
 ])}## When to use the CLI
 
-Use the bundled \`hb-sdk\` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, or managing the CLI's own Heybox auth cache.
+Use the bundled \`hb-sdk\` CLI when the task is about creating an external mini-program project, starting local Vite development, debugging SDK calls in a browser mock runtime host, managing the CLI's own Heybox auth cache, or inspecting/switching the developer platform current entity for remote mini-program management.
 
 Do not use the CLI to replace iframe SDK calls. \`hb-sdk login\` is for CLI commands only and does not change \`auth.login()\`, \`user.getInfo()\`, \`network.request()\`, or mock-host user state.
 
@@ -311,7 +354,9 @@ The CLI, templates, and mock host are owned by \`${packageJson.name}\`. Do not c
 
 ## Command surface
 
-${fenced('ts', cliEntry)}
+${fenced('text', cliCommandSurface)}
+
+Top-level \`hb-sdk deploy\` has been hard-cut and must not be documented as a valid compatibility alias. Keep \`hb-sdk login\` top-level because it manages CLI login state, not a specific remote mini-program.
 
 ## Create a mini-program template
 
@@ -334,16 +379,49 @@ Use \`hb-sdk dev\` for local browser SDK debugging. Use the Mock runtime host's
 
 ${cliDeploySection}
 
+${cliRemoteEntityDeploySection}
+
 Agent rules:
 
-- Use \`hb-sdk deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
-- Use \`--api-base-url <url>\` or \`HB_SDK_API_BASE_URL\` only for deploy backend APIs.
+- Use \`hb-sdk remote deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
+- Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
+- Never recommend top-level \`hb-sdk deploy\`; it has been removed rather than retained as a compatibility alias.
+- After non-auto deploy succeeds, suggest \`hb-sdk remote versions\` and then \`hb-sdk remote release <version>\` after approval. Do not send the user to Open for manual publish when the CLI command exists.
+- Use \`hb-sdk remote allowlist add <heybox_id>\` when preview access needs to be granted.
+- Use \`--api-base-url <url>\` or \`HB_SDK_API_BASE_URL\` for remote platform backend APIs.
 - Use \`--allow-unsafe-api-base-url\` or \`HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1\` only for local backend debugging against non-Heybox or non-HTTPS API origins.
-- Use \`--login-base-url <url>\` or \`HB_SDK_LOGIN_BASE_URL\` for CLI browser login and deploy login-environment validation.
+- Use \`--login-base-url <url>\` or \`HB_SDK_LOGIN_BASE_URL\` for CLI browser login and remote command login-environment validation.
 - Use \`packages/hb-sdk/src/cli/config.ts\` with \`RylaiServiceTagConfig\` only when Heybox backend API requests need the development-only \`x-rylai-service-tag\` header and matching \`special_tag\` query parameter.
 - Custom base URLs must be origin-only; API origins must be Heybox trusted HTTPS unless the unsafe debug switch is explicit. Do not include path, query, or hash.
 - Do not expect custom base URLs to affect \`hb-sdk doctor\`, npm latest checks, or mock-host \`network.request()\`.
 
+## Remote entity scope
+
+${cliRemoteEntitySection}
+
+Agent rules:
+
+- Treat the server-side current entity as the authority for remote create, bind, deploy, list, access, versions, preview, release, withdraw, take-down, and reopen workflows.
+- Treat CLI \`selectedEntity\` as a display/debug snapshot only; it can drift from the server-side current entity and must not be used as a permission source.
+- Use \`hb-sdk remote entity current\` when a user needs to confirm which entity create/deploy will use.
+- Use \`hb-sdk remote entity switch <entity-id>\` to change entity scope. Do not recommend \`--entity-id\` or an environment variable as a remote command override.
+- \`hb-sdk remote list\` lists mini-programs in the current entity scope only; do not promise cross-entity aggregation.
+
+## Remote management commands
+
+${cliRemoteSection}
+
+Agent rules:
+
+- Use \`hb-sdk remote entity list/current/switch\` for developer entity inspection and switching.
+- Use \`hb-sdk remote create --name <name>\` for create-and-bind and \`hb-sdk remote bind <mini-program-id>\` for binding an existing manageable remote mini-program.
+- Explain that \`remote create\` creates under the current entity and that multi-entity non-TTY usage must confirm with \`--yes\`; \`--yes\` confirms current-entity usage but does not switch entities.
+- Explain that \`remote bind\` verifies the mini-program is manageable by the current entity and does not write \`package.json.heybox.miniProgramId\` on entity mismatch.
+- Use \`hb-sdk remote info\`, \`hb-sdk remote update\`, \`hb-sdk remote access\`, \`hb-sdk remote list\`, \`hb-sdk remote versions\`, \`hb-sdk remote preview <version>\`, and \`hb-sdk remote allowlist ...\` instead of sending users to Open when a matching CLI command exists.
+- Treat \`hb-sdk remote list\` as discovery only. Dangerous write commands still target the bound mini-program from \`package.json.heybox.miniProgramId\`.
+- Require confirmation or \`--yes\` for \`hb-sdk remote release\`, \`hb-sdk remote withdraw\`, \`hb-sdk remote take-down\`, and \`hb-sdk remote reopen\`.
+- Use \`--json\` for script consumption and keep stdout as exactly one JSON object.
+
 ## CLI login cache
 
 ${cliLoginSection}
@@ -351,6 +429,7 @@ ${cliLoginSection}
 Agent rules:
 
 - Keep CLI auth cache separate from iframe SDK login state.
+- Keep \`selectedEntity\` guidance explicit: it is only a hint snapshot, while every remote command uses the server-side current entity.
 - It is correct to say status output is redacted.
 - Do not expose or template pkey, cookie, token, or private credential values.
 - Use \`hb-sdk login clear\` only to clear the \`hb-sdk\` CLI namespace.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.4.4+skill.77f95b6757e8",
+  "skillVersion": "0.4.6+skill.1c7149a95a0b",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.4.4",
-    "compatibility": "0.4.4"
+    "version": "0.4.6",
+    "compatibility": "0.4.6"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-77f95b6757e86f4fd6ec2bc865bab4a3781403d5e1db9b3e729407a7fbd7f01a"
+  "integrity": "sha256-1c7149a95a0b5d0ffeaa479456186dab5f3bc06865fd5c28a975682381267811"
 }

package/types/miniapp-publish/index.d.ts

@@ -1,7 +1,22 @@
 export declare const MINIAPP_UPLOAD_SCOPE = "activity";
 export declare const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
+export declare const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = "/mall/developer/user_miniprogram/access_status";
+export declare const DEVELOPER_ENTITY_LIST_API_PATH = "/mall/developer/entity/list";
+export declare const DEVELOPER_ENTITY_SWITCH_API_PATH = "/mall/developer/entity/switch";
+export declare const LIST_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/list";
+export declare const CREATE_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/create";
+export declare const UPDATE_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/update";
+export declare const DETAIL_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/detail";
+export declare const USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist";
+export declare const UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH = "/mall/developer/user_miniprogram/preview_allowlist/update";
 export declare const PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/precheck";
 export declare const SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH = "/mall/developer/user_miniprogram/version/submit_audit";
+export declare const USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH = "/mall/developer/user_miniprogram/version/preview_info";
+export declare const WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/withdraw";
+export declare const RELEASE_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/release";
+export declare const TAKE_DOWN_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/take_down";
+export declare const REOPEN_USER_MINIPROGRAM_API_PATH = "/mall/developer/user_miniprogram/reopen";
+export declare const LIST_USER_MINIPROGRAM_VERSION_API_PATH = "/mall/developer/user_miniprogram/version/list";
 export { isValidMiniappManifestVersion as isValidVersion } from '../miniapp-manifest/schema';
 export declare function normalizeRelativePath(relativePath: string): string;
 export declare function relativePathContainsNodeModulesSegment(relativePath: string): boolean;