@heybox/hb-sdk 0.8.0 → 0.8.1-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.8.0",
+  "version": "0.8.1-alpha.10",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -62,7 +62,7 @@
     "skills": "1.5.23",
     "undici": "^7.28.0",
     "ws": "^8.18.0",
-    "@heybox/hb-sdk-protocol": "0.8.0"
+    "@heybox/hb-sdk-protocol": "0.8.1-alpha.10"
   },
   "peerDependencies": {
     "vite": ">=5"
@@ -114,11 +114,11 @@
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
     "@heybox-domain/heybox-theme": "~0.1.0",
-    "@heybox/hb-api": "~1.28.2",
-    "@heybox/hb-sdk-runtime": "~0.8.0",
+    "@heybox/hb-api": "~1.28.3",
+    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
+    "@heybox/hb-sdk-runtime": "~0.8.1-alpha.10",
     "@heybox/runtime": "~0.2.0",
     "@heybox/runtime-policy": "~0.2.0",
-    "@heybox-domain/heybox-vue3-ui": "~0.1.0",
     "@heybox/runtime-transport-fetch": "~0.2.0"
   },
   "publishConfig": {
@@ -171,11 +171,11 @@
     "check:compatibility-evidence": "node scripts/validate-compatibility-evidence.mjs",
     "check:api-semver": "node ../../ops/jobs/hb-sdk-docs-contract/semantic-diff.cjs",
     "clean": "rimraf ./dist && rimraf ./types",
-    "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
+    "test:unit": "vitest run",
     "test:types:characterization": "tsc -p tsconfig.characterization.json --noEmit --pretty false",
     "test:types:browser-dev-host": "vue-tsc -p tsconfig.browser-dev-host.json --noEmit --pretty false",
     "test:types": "pnpm run test:types:characterization && pnpm run test:types:browser-dev-host",
-    "test:e2e:browser-dev-host": "pnpm run build:browser-dev-host && NODE_OPTIONS='--conditions=heybox' vitest run --config vitest.browser-dev-host-e2e.config.ts",
+    "test:e2e:browser-dev-host": "pnpm run build:lib && pnpm run build:cli:bundle && NODE_OPTIONS='--conditions=heybox' vitest run --config vitest.browser-dev-host-e2e.config.ts",
     "test:create-template:artifact": "node scripts/test-create-template-artifact.mjs",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",
     "test:vite": "pnpm run build:hb-sdk-protocol && pnpm run build:hb-api-contract && vitest run --config vitest.vite.config.ts",
@@ -183,14 +183,12 @@
     "changelog:draft": "node scripts/changelog-draft.cjs",
     "check:changelog": "node scripts/check-changelog.cjs",
     "release:verify-tarball": "node scripts/skill/verify-tarball-install.mjs",
-    "test:release": "node --test scripts/public-changelog.test.mjs scripts/public-changelog-workflow.test.cjs scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs ../../ops/jobs/release-hb-sdk/docs-release-contract.test.cjs ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.test.cjs",
+    "test:release": "node --test scripts/public-changelog.test.mjs scripts/public-changelog-workflow.test.cjs scripts/release-family.test.cjs ../../ops/jobs/publish-changed-packages/publish.test.cjs",
     "test:compatibility-evidence": "node --test scripts/validate-compatibility-evidence.test.mjs",
     "release:prepare": "node scripts/release-prepare.cjs",
     "release:tag": "node scripts/release-tag.cjs",
     "release:family:dry-run": "node ../../ops/jobs/publish-changed-packages/publish.cjs --dry-run",
     "release:family:promote": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action promote",
-    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback",
-    "release:stable:promote": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action promote",
-    "release:stable:rollback": "node ../../ops/jobs/release-hb-sdk/stable-promote-coordinator.cjs --action rollback"
+    "release:family:rollback": "node ../../ops/jobs/publish-changed-packages/publish.cjs --family-action rollback"
   }
 }

package/skill/SKILL.md

@@ -21,6 +21,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 1. For root SDK imports, singleton usage, modules, and errors, read `references/api-root.md`.
 2. For host/runtime protocol contracts only, read `references/api-protocol.md`. Do not use this reference for mini-program business code.
 3. For common business flows, read `references/recipes.md`.
+   For managed desktop programs, read the `Managed Companion` section and preserve its trust boundaries.
 4. For CLI commands, production builds, local debugging, device debugging, CLI login, Agent Skill doctor, and update reminders, read `references/cli.md`.
 5. For allowed/forbidden capabilities and security boundaries, read `references/safety-boundaries.md`.
 6. For Vite build manifest behavior, read `references/api-root.md` and `references/safety-boundaries.md`.
@@ -52,14 +53,18 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 12. Use `share.showShareMenu({ extra })` to open the share menu or `share.copyLink({ extra })` to copy and return the mini-program share link. `share.showShareMenu()` always uses the platform `common_share` landing page and does not accept a custom `url`. Read the JSON-compatible page state synchronously with `share.getExtra()` after launch, validate the developer-defined fields, and fall back to the default page when it returns `undefined`.
 13. New PC enables the retained `files` and `network.download()` contract with persistent sandbox storage, single-file/directory pickers, exact File saving, and public-network streaming downloads. Mobile, Web, Browser Dev Host, and legacy PC return `METHOD_FORBIDDEN` and provide no memory/Blob fallback. Call `files.pickFiles()` / `pickDirectory()` / `saveFile()` only from trusted user actions; `saveFile()` accepts only `suggestedName`, `remove()` only deletes sandbox objects, and non-empty directories require `remove({ recursive: true })`.
 14. Use `network.download()` only with an SDK-created File/Directory target. It is GET-only, does not follow redirects, and exposes local `AbortSignal` / progress callbacks without sending functions over the bridge. Abort is a cancellation intent; a Host commit that already won still resolves successfully.
+15. Use `companion.prepare()` and `companion.launch()` only from separate trusted user actions. Launch does not prepare implicitly. Treat stdio as raw `Uint8Array` with at-least-once output delivery, and implement business framing and sequence de-duplication explicitly.
+16. Use `environment.getInfo()` for the immutable runtime, Host App, canonical Mini-program, operating-system, and SDK version snapshot. It waits for the handshake automatically. Use `environment.getInfoSync()` only after `getHandshakeState().status === 'ready'` or inside a ready-state subscription; before that it throws `ENVIRONMENT_NOT_READY`.
+17. Treat missing environment strings as `null` and unknown enum values as `unknown`. Only `sdk.version` is SemVer; do not compare the other opaque version strings or use any environment field for authentication, authorization, or risk control.
 
 ## Step 5: Use CLI workflows
 
 1. Use `hb-sdk create <project-name>` to scaffold a workshop mini-program.
 2. Use `hb-sdk dev` for Browser Mock and Mobile App debugging. Browser debugging can start without CLI login, project binding, or a remote Dev Context; capabilities that need those inputs fail explicitly. Mobile uses the single QR entry with the `open_inapp` and `heybox://` `openWindow` wrapper around a LAN short URL, then opens `heybox-mini-dev://sandbox` with the complete launch context.
-3. The debugging page does not edit permissions. Treat the validated remote permission snapshot as canonical Runtime input. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
+3. The debugging page does not edit permissions. Treat the effective intersection of the current project declaration and validated remote approval as canonical Runtime input. Mobile debugging preserves `useOfficialDomain: true` only when both inputs allow it, refreshes the effective permissions before opening on a phone, and never accepts a browser-side permission override. Use `--port`, `--browser-dev-host-port`, and `--no-open` to control local endpoints and browser opening. Select a Mobile network interface the device can reach. `launch.json` is a LAN discovery document, not authentication, encryption, signing, or HMAC protection.
+   For real PC Companion debugging, configure local artifacts in `package.json#heybox.companions`, keep `miniappManifest()` enabled, bind the project, and ensure COA has approved `companion`. `hb-sdk dev` validates immutable snapshots without requiring an upload; config or artifact changes rotate the snapshot while existing Sessions retain their original artifact. Prepare and launch the new artifact explicitly. Check separate Browser, Mobile and PC Companion readiness in the debugging workbench. Without a local declaration, use Browser Fake only for state/UI integration.
 4. Use `hb-sdk build [--env <name>] [--verbose]` as the recommended production build entry. It directly owns the Vite build, always cleans and writes `dist/`, and works without CLI login, project binding, or network access.
-5. Keep `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the required Manifest or Runtime gate output is missing.
+5. Declare the actual supported platforms in `package.json#heybox.platforms` and keep the no-argument `miniappManifest()` explicitly enabled in `vite.config.ts`; `hb-sdk build` must fail when the declaration, Manifest, or Runtime gate output is missing or inconsistent.
 6. Keep project typechecking in `scripts.build`, for example `vue-tsc --noEmit && hb-sdk build`; `hb-sdk build` does not run typechecking or invoke `scripts.build` itself.
 7. Existing projects may continue to use `vite build`; do not auto-migrate them. Do not invent `--mode`, `--json`, config, or output-directory flags for `hb-sdk build`.
 8. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` for remote management, publishing, Mobile debugging, and optional Browser Mock Host `heybox-session` requests. Browser debugging itself can start without CLI login. Mini-program code must still call `auth.login()`; the debug page only confirms authorization. Do not paste CLI credentials into page JavaScript. Phone debugging continues to use the App login.
@@ -88,16 +93,19 @@ For workshop mini-program business code:
 7. Do not use `network.request()` to reach platform-reserved runtime auth or OpenAPI internal paths.
 8. Do not expose credentials or describe internal Host authorization state machines and routes in app-facing guidance.
 9. Do not invent string paths, File System Access API handles, Blob downloads, uploads, Range/resume, external deletion, move, append, or persistent external grants. Public file operations use only SDK-created handles; deletion is limited to SDK sandbox handles.
+10. Do not pass executable paths, dynamic args, cwd, environment variables, shell commands, URLs, hashes, PID, or native handles through `companion`; reviewed Manifest declarations are the only launch source.
+11. Do not treat `environment.*` as a device-fingerprint or trusted backend signal. It intentionally excludes account data, device identifiers, model, UA, CPU, and memory; use `viewport.getWindowInfo()` for screen geometry.
 
 For CLI and local development:
 
 1. Do not print, persist in templates, or pass through pkey, cookies, tokens, or private credentials.
 2. Do not skip `auth.login()` in mini-program code. Browser Mock may reuse the Node `hb-sdk login` session for Host network requests, but the page must still call `auth.login()` and handle the authorization dialog. Never paste CLI credentials into page JavaScript.
 3. Use the built-in local debugging page instead of creating another browser Mock.
-4. Keep the Vite `miniappManifest()` plugin enabled.
+4. Keep target platforms in `package.json#heybox.platforms` and the no-argument Vite `miniappManifest()` plugin enabled. Do not configure platforms in Vite or maintain a second platform list.
 5. Do not suggest changing or resetting permissions in the `hb-sdk dev` debugging page; that UI does not exist. Diagnose permission behavior from the remote snapshot and capability result.
 6. Treat browser Mock results as development feedback only. Validate permissions, identity flows, and user interactions again in a real Heybox client before publishing.
 7. The Browser Dev Host offers iPhone 16 Pro Max (`440 x 956`) and Pixel 9 Pro (`410 x 914`) presets. Switching a preset must preserve the iframe, Runtime session, and page state. Authorization/action dialogs, Toast, Loading, and vibration feedback render inside the preview. Use the upper-right QR popover as the only Mobile QR entry.
+8. Companion Fake scenarios do not execute a local program and are not Windows/macOS release evidence. V1 only supports normal-privilege launch and rejects `elevation: 'required'` at build time. Require target-platform new PC validation for archive integrity, stdio, exit, and process-tree cleanup.
 
 For host/runtime/protocol-maintenance code:
 

package/skill/references/api-protocol.md

@@ -176,7 +176,10 @@ export type {
   MiniProgramNetworkMethod,
   MiniProgramNetworkParams,
   MiniProgramNetworkRequestMethod,
+  MiniProgramOperatingSystemName,
   MiniProgramRuntimePermissionEntry,
+  MiniProgramRuntimeEnvironmentInfo,
+  MiniProgramRuntimeMode,
   MiniProgramRuntimePermissionsSnapshot,
   MiniProgramRuntimePermissionStatus,
   MiniProgramSafeArea,
@@ -215,6 +218,7 @@ export type {
   SaveFilePayload,
   SaveFileResult,
   SDKHandshakePayload,
+  SDKHandshakeResult,
   SetClipboardPayload,
   SetClipboardResult,
   SetNavigationBarStylePayload,
@@ -295,12 +299,12 @@ Reference 由 `@heybox/hb-sdk` 的公开导出与源码注释自动生成，不
 
 | 导出面 | Classes | Functions | Interfaces | Types | Constants |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Root API | 2 | 4 | 65 | 60 | 1 |
-| Protocol API | 0 | 13 | 56 | 90 | 47 |
+| Root API | 2 | 4 | 75 | 73 | 3 |
+| Protocol API | 0 | 13 | 58 | 90 | 47 |
 | Miniapp Publish API | 0 | 5 | 2 | 0 | 0 |
-| Vite API | 0 | 1 | 5 | 1 | 1 |
+| Vite API | 0 | 1 | 5 | 1 | 2 |
 
-<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=3; fingerprint=660a21ad77c32f30dbc7ebb02b053ebce2a7c6e7301cc805a5cdd1a75572fbb2 -->
+<!-- Generated by apps/docs/hb-sdk/scripts/generate-api-docs.ts; schemaVersion=4; fingerprint=a80eea1bb8b0d64255afcb4a664911f025aeae33f3f766c9b126f55668400178 -->
 
 ## SDK API