@realsee/vr-cli 0.1.5 → 0.2.0

package/skills/realsee-vr-app/references/dnalogel-openapi-recipes.md

@@ -152,9 +152,22 @@ export type PanoTagContentDto =
       readonly data: { readonly modelUrl: string };
     };
 
+export type PanoTagPointStyleDto = {
+  readonly url?: string;
+  readonly width?: number;
+  readonly scale?: number;
+  readonly enabled?: boolean;
+  readonly ratio?: number;
+};
+
+export type PanoTagStyleDto = {
+  readonly point: PanoTagPointStyleDto;
+};
+
 export type PanoTagDto = {
   readonly id?: string | number;
   readonly enabled?: boolean;
+  readonly style?: PanoTagStyleDto;
 } & PanoTagAnchorDto &
   PanoTagContentDto;
 
@@ -164,7 +177,7 @@ export interface PanoTagCapabilityDto {
 }
 ```
 
-The starter intentionally omits `globalConfig` and `contentTypeConfig`: the installed SDK config allows callbacks, DOM values, and Three objects that are not a safe BFF contract. Add an explicit JSON-safe whitelist DTO only when the product needs a specific config field. Canonical 3.81.2 content types not shown above (`Marketing`, `MediaPlane`, `MediaModel`, `Custom`, and `Unknown`) must be rejected until a product-specific serializable schema, parser arm, and converter arm are supplied. Never accept arbitrary `Custom`/`Unknown` objects by default.
+The starter intentionally limits `style` to the JSON-safe `point` artwork fields used by ordinary tag icons. Do not pass the complete SDK `TagStyle` through the BFF: add another explicit DTO/parser/converter whitelist only when the product needs `boxOrpolygon`, `mask`, animation, or another style field. The starter also omits `globalConfig` and `contentTypeConfig`: the installed SDK config allows callbacks, DOM values, and Three objects that are not a safe BFF contract. Add an explicit JSON-safe whitelist DTO only when the product needs a specific config field. Canonical 3.81.2 content types not shown above (`Marketing`, `MediaPlane`, `MediaModel`, `Custom`, and `Unknown`) must be rejected until a product-specific serializable schema, parser arm, and converter arm are supplied. Never accept arbitrary `Custom`/`Unknown` objects by default.
 
 ### Runtime parser
 
@@ -240,6 +253,57 @@ const parseMediaItem = (value: unknown, path: string): MediaItemDto => {
   }
 };
 
+const optionalPositiveFinite = (
+  record: Record<string, unknown>,
+  key: string,
+  path: string,
+) => {
+  const value = record[key];
+  if (value === undefined) return undefined;
+  const parsed = requireFinite(value, `${path}.${key}`);
+  if (parsed <= 0) {
+    throw new RealseeOpenApiError(`${path}.${key} 必须大于 0。`);
+  }
+  return parsed;
+};
+
+const optionalBoolean = (
+  record: Record<string, unknown>,
+  key: string,
+  path: string,
+) => {
+  const value = record[key];
+  if (value !== undefined && typeof value !== "boolean") {
+    throw new RealseeOpenApiError(`${path}.${key} 必须是布尔值。`);
+  }
+  return value;
+};
+
+const parseStyle = (
+  record: Record<string, unknown>,
+  path: string,
+): PanoTagStyleDto | undefined => {
+  if (record.style === undefined) return undefined;
+  const style = requireRecord(record.style, `${path}.style`);
+  if (style.point === undefined) return undefined;
+  const pointPath = `${path}.style.point`;
+  const point = requireRecord(style.point, pointPath);
+  const url = optionalString(point, "url", pointPath);
+  const width = optionalPositiveFinite(point, "width", pointPath);
+  const scale = optionalPositiveFinite(point, "scale", pointPath);
+  const enabled = optionalBoolean(point, "enabled", pointPath);
+  const ratio = optionalPositiveFinite(point, "ratio", pointPath);
+  return {
+    point: {
+      ...(url ? { url } : {}),
+      ...(width !== undefined ? { width } : {}),
+      ...(scale !== undefined ? { scale } : {}),
+      ...(enabled !== undefined ? { enabled } : {}),
+      ...(ratio !== undefined ? { ratio } : {}),
+    },
+  };
+};
+
 const parseAnchor = (
   record: Record<string, unknown>,
   path: string,
@@ -403,20 +467,22 @@ const parsePanoTag = (value: unknown, index: number): PanoTagDto => {
   if (record.enabled !== undefined && typeof record.enabled !== "boolean") {
     throw new RealseeOpenApiError(`${path}.enabled 必须是布尔值。`);
   }
+  const style = parseStyle(record, path);
   return {
     ...(id !== undefined ? { id } : {}),
     ...(record.enabled !== undefined ? { enabled: record.enabled } : {}),
+    ...(style ? { style } : {}),
     ...parseAnchor(record, path),
     ...parseContent(record, path),
   };
 };
 ```
 
-The parser above implements every discriminator in the starter DTO and rejects all others rather than passing them through. Return `{ version?, tagList: data.tagList.map(parsePanoTag) }` only after the complete array parses. Validate optional `version` as a non-empty string when present.
+The parser above implements every discriminator in the starter DTO and rejects all others rather than passing them through. It preserves only `style.point.url`, `width`, `scale`, `enabled`, and `ratio`; all other SDK style fields require their own explicit DTO, parser, and converter support. Return `{ version?, tagList: data.tagList.map(parsePanoTag) }` only after the complete array parses. Validate optional `version` as a non-empty string when present.
 
 ### Exhaustive browser conversion and feature ownership
 
-Convert readonly DTO arrays into mutable SDK arrays and declare the converter's return type as `Tags`; do not cast at the final boundary:
+Convert readonly DTO arrays into mutable SDK arrays and declare the converter's return type as `Tags`; do not cast at the final boundary. The snippet assumes `featureThumbnailURL` is imported from the application-owned image adapter in the next recipe so every plugin image, including `style.point.url`, is validated and bounded at this boundary:
 
 ```ts
 import {
@@ -496,13 +562,15 @@ const toSdkMedia = (media: MediaItemDto) =>
   media.type === "Image"
     ? {
         type: "Image" as const,
-        url: media.url,
-        ...(media.thumbnail ? { thumbnail: media.thumbnail } : {}),
+        url: featureThumbnailURL(media.url, 1024),
+        thumbnail: featureThumbnailURL(media.thumbnail ?? media.url, 256),
       }
     : {
         type: "Video" as const,
         url: media.url,
-        ...(media.videoCoverUrl ? { videoCoverUrl: media.videoCoverUrl } : {}),
+        ...(media.videoCoverUrl
+          ? { videoCoverUrl: featureThumbnailURL(media.videoCoverUrl, 512) }
+          : {}),
       };
 
 const toSdkContent = (tag: PanoTagContentDto) => {
@@ -535,9 +603,24 @@ const toSdkContent = (tag: PanoTagContentDto) => {
   }
 };
 
+const toSdkStyle = (style: PanoTagStyleDto) => ({
+  point: {
+    ...(style.point.url
+      ? { url: featureThumbnailURL(style.point.url, 256) }
+      : {}),
+    ...(style.point.width !== undefined ? { width: style.point.width } : {}),
+    ...(style.point.scale !== undefined ? { scale: style.point.scale } : {}),
+    ...(style.point.enabled !== undefined
+      ? { enabled: style.point.enabled }
+      : {}),
+    ...(style.point.ratio !== undefined ? { ratio: style.point.ratio } : {}),
+  },
+});
+
 const toSdkTag = (tag: PanoTagDto): Tags["tagList"][number] => ({
   ...(tag.id !== undefined ? { id: tag.id } : {}),
   ...(tag.enabled !== undefined ? { enabled: tag.enabled } : {}),
+  ...(tag.style ? { style: toSdkStyle(tag.style) } : {}),
   ...toSdkAnchor(tag),
   contentType: tag.contentType,
   data: toSdkContent(tag),
@@ -594,26 +677,7 @@ export const featureThumbnailURL = (source: string, size: 256 | 512 | 1024) =>
   });
 ```
 
-Apply it at the DTO-to-SDK conversion boundary, where the display context is known:
-
-```ts
-const toSdkMedia = (media: MediaItemDto) =>
-  media.type === "Image"
-    ? {
-        type: "Image" as const,
-        // Popover artwork does not need the original.
-        url: featureThumbnailURL(media.url, 1024),
-        // A list thumbnail needs far less; fall back to the same source when absent.
-        thumbnail: featureThumbnailURL(media.thumbnail ?? media.url, 256),
-      }
-    : {
-        type: "Video" as const,
-        url: media.url, // video streams are not image-transform targets
-        ...(media.videoCoverUrl
-          ? { videoCoverUrl: featureThumbnailURL(media.videoCoverUrl, 512) }
-          : {}),
-      };
-```
+The PanoTag converter above applies this adapter at the DTO-to-SDK boundary: content artwork uses 256–1024 px variants, video cover artwork uses 512 px, and `style.point.url` uses a 256 px variant. Keep video stream URLs unchanged.
 
 Per-capability targets:
 

package/skills/realsee-vr-app/references/five-runtime.md

@@ -5,8 +5,8 @@
 - Accept Work through a `WorkSource` boundary, not from a hardcoded business endpoint or local `work.json`.
 - The browser route is `/{resourceCode}` and the Viewer calls only the same-origin `/api/work/{resourceCode}` contract. Do not add `VITE_WORK_URL` or embed a business endpoint.
 - The generated Fastify BFF is a replaceable TypeScript example. Keep the shared contracts in `server/types.ts`, Realsee token exchange/cache and upstream calls in `server/realsee-open-api.ts`, the framework-neutral browser envelope in `server/work-service.ts`, and HTTP adaptation in `server/work-route.ts`. Node runs these files directly through type stripping, so `server/` must stay erasable-only and keep explicit `.ts` import extensions.
-- A Go or other backend may replace `server/`, but must preserve onboarding `GET /api/work` and return `{ work, workCode, baseURL?, capabilities?: { modelFloorplan } }` without exposing credentials or tokens. The explicit resource-code route is development-only compatibility.
-- Use the single `.env.example` as the server/deployment schema. `npm run setup` writes AK, SK and the default `resourceCode` to `.env.development`; only the BFF reads `REALSEE_GATEWAY_ENDPOINT`, `REALSEE_GATEWAY_APP_KEY`, `REALSEE_GATEWAY_APP_SECRET` and `REALSEE_DEFAULT_RESOURCE_CODE`. Browser code reads none of them.
+- A Go or other backend may replace `server/`, but must preserve `GET /api/work/{resourceCode}` and return `{ work, workCode, baseURL?, capabilities?: { modelFloorplan } }` without exposing credentials or tokens. `GET /api/work` is only an optional `REALSEE_DEFAULT_RESOURCE_CODE` fallback; without one it returns a controlled 4xx before any upstream request.
+- Use the single `.env.example` as the server/deployment schema. `npm run setup` always writes AK/SK and writes `REALSEE_DEFAULT_RESOURCE_CODE` only when the paired Portal approval (or the compatible v1 payload) supplies an optional `resourceCode`; its default path is Portal pairing (`--no-wait`/`--complete` split flow for agents, `--paste` as the hidden-input fallback), and `REALSEE_GATEWAY_APP_KEY`/`REALSEE_GATEWAY_APP_SECRET` environment variables take precedence and skip pairing. Success and failure envelopes use `ok` (`{"ok":true,...}` on stdout, `{"ok":false,"error":{...}}` on stderr) — judge them with `ok===true`, never a `code` field — and only a masked AK may appear in output. Only the BFF reads `REALSEE_GATEWAY_ENDPOINT`, `REALSEE_GATEWAY_APP_KEY`, `REALSEE_GATEWAY_APP_SECRET` and optional `REALSEE_DEFAULT_RESOURCE_CODE`. Browser code reads none of them. The default `deploy.json.requiredEnv` contains only AK/SK.
 - Keep the real `REALSEE_GATEWAY_APP_SECRET`, access token and OpenAPI authorization logic in the BFF environment or secret manager. Never expose them through `VITE_*`, Vite `define/envPrefix`, client source, query strings, browser request headers, logs or returned Work envelopes.
 - Carry `workCode`, optional `baseURL`, raw Work and optional initial State together. Preset feature input must be explicit; only `presetData.panoTagList` or a validated named feature-data contract may feed a plugin.
 - Never infer PanoTag from generic `tags`, `tagList` or `tag_list` fields. `/open/v3/hot/list` is authoritative only after its envelope and typed tag records are validated by a named BFF adapter.

package/skills/realsee-vr-app/scripts/verify-project.mjs

@@ -39,14 +39,22 @@ const expectedDev = {
   'typescript-eslint': '8.68.0',
   vite: '5.4.14',
 }
+const releasePackageFormat = 'node-vite-bff-v1'
+const releaseZipPackage = 'adm-zip'
+const releaseZipVersion = '0.6.0'
+const releaseRequiredEnvKeys = [
+  'REALSEE_GATEWAY_APP_KEY',
+  'REALSEE_GATEWAY_APP_SECRET',
+]
 const requiredEnvKeys = [
   'APP_ID',
   'REALSEE_GATEWAY_ENDPOINT',
   'REALSEE_GATEWAY_APP_KEY',
   'REALSEE_GATEWAY_APP_SECRET',
-  'REALSEE_DEFAULT_RESOURCE_CODE',
   'REALSEE_SOURCE',
 ]
+const optionalEnvExampleMarker =
+  '# REALSEE_DEFAULT_RESOURCE_CODE=example-resource-code'
 const credentialEnvKeys = [
   'REALSEE_GATEWAY_APP_KEY',
   'REALSEE_GATEWAY_APP_SECRET',
@@ -55,6 +63,7 @@ const secretEnvKeys = ['REALSEE_GATEWAY_APP_SECRET']
 const requiredFiles = [
   'package.json',
   'package-lock.json',
+  'deploy.json',
   'README.md',
   'index.html',
   'tsconfig.json',
@@ -68,9 +77,12 @@ const requiredFiles = [
   '.vr-cli.json',
   'eslint.config.mjs',
   'prettier.config.mjs',
+  'scripts/package-vibe-release.mjs',
   'scripts/setup-config.mjs',
   'scripts/setup-config.test.mjs',
   'scripts/setup.mjs',
+  'scripts/pairing.mjs',
+  'scripts/pairing.test.mjs',
   'server/types.ts',
   'server/config.ts',
   'server/check-config.ts',
@@ -365,9 +377,11 @@ function versionAtLeast(actual, required) {
   if (actualVersion.prerelease === requiredVersion.prerelease) return true
   if (actualVersion.prerelease === null) return true
   if (requiredVersion.prerelease === null) return false
-  return actualVersion.prerelease.localeCompare(requiredVersion.prerelease, 'en', {
-    numeric: true,
-  }) >= 0
+  return (
+    actualVersion.prerelease.localeCompare(requiredVersion.prerelease, 'en', {
+      numeric: true,
+    }) >= 0
+  )
 }
 
 async function currentNpmVersion() {
@@ -439,6 +453,11 @@ try {
     failures.push(`engines.node must equal ${nodeEngine}`)
   if (pkg.engines?.npm !== npmEngine)
     failures.push(`engines.npm must equal ${npmEngine}`)
+  if (pkg.devDependencies?.[releaseZipPackage] !== releaseZipVersion) {
+    failures.push(
+      `${releaseZipPackage} must stay locked at ${releaseZipVersion} for release packaging`,
+    )
+  }
   for (const [declared, baseline] of [
     [pkg.dependencies, expected],
     [pkg.devDependencies, expectedDev],
@@ -482,7 +501,16 @@ try {
   for (const [name, markers] of [
     ['dev', ['check:env', 'concurrently']],
     ['setup', ['scripts/setup.mjs']],
-    ['test:setup', ['--test', 'scripts/setup-config.test.mjs']],
+    ['setup:complete', ['scripts/setup.mjs', '--complete']],
+    [
+      'test:setup',
+      [
+        '--test',
+        'scripts/setup-config.test.mjs',
+        'scripts/project-identity.test.mjs',
+        'scripts/pairing.test.mjs',
+      ],
+    ],
     ['dev:bff', ['--env-file-if-exists=.env.development', 'server/index.ts']],
     ['dev:web', ['vite']],
     [
@@ -499,6 +527,7 @@ try {
     ['check:bff', ['typecheck:bff']],
     ['deps:relock', ['npm install --package-lock-only']],
     ['deps:install', ['npm ci']],
+    ['package:vibe-release', ['node scripts/package-vibe-release.mjs']],
     [
       'start',
       [
@@ -532,13 +561,17 @@ try {
           'package-lock.json root name/version must match package.json',
         )
       }
+      if (
+        lockRoot.devDependencies?.[releaseZipPackage] !== releaseZipVersion ||
+        lockfile.packages?.[`node_modules/${releaseZipPackage}`]?.version !==
+          releaseZipVersion
+      ) {
+        failures.push(
+          `package-lock.json must declare and resolve ${releaseZipPackage}@${releaseZipVersion}`,
+        )
+      }
       for (const [lockDeclared, declared, baseline, label] of [
-        [
-          lockRoot.dependencies,
-          pkg.dependencies,
-          expected,
-          'dependencies',
-        ],
+        [lockRoot.dependencies, pkg.dependencies, expected, 'dependencies'],
         [
           lockRoot.devDependencies,
           pkg.devDependencies,
@@ -588,6 +621,123 @@ try {
   failures.push(`package metadata: ${String(error)}`)
 }
 
+if ((await exists('deploy.json')) && (await exists('package.json'))) {
+  try {
+    const manifest = await readFile(path.join(root, 'deploy.json'), 'utf8').then(
+      JSON.parse,
+    )
+    const isRecord = (value) =>
+      value !== null && typeof value === 'object' && !Array.isArray(value)
+    const manifestErrors = []
+    let requiredEnvError = null
+    let healthError = null
+
+    if (!isRecord(manifest)) {
+      manifestErrors.push('must be a JSON object')
+    } else {
+      if (manifest.packageFormat !== releasePackageFormat) {
+        manifestErrors.push(
+          `packageFormat must equal ${releasePackageFormat}`,
+        )
+      }
+      const allowedFields = new Set([
+        'packageFormat',
+        'name',
+        'requiredEnv',
+        'resources',
+        'domain',
+        'healthCheck',
+      ])
+      const unsupportedField = Object.keys(manifest).find(
+        (field) => !allowedFields.has(field),
+      )
+      if (unsupportedField) {
+        manifestErrors.push(`unsupported field ${unsupportedField}`)
+      }
+
+      if (
+        !Array.isArray(manifest.requiredEnv) ||
+        manifest.requiredEnv.length > 20
+      ) {
+        requiredEnvError = 'must be an array with no more than 20 entries'
+      } else {
+        const names = new Set()
+        for (const raw of manifest.requiredEnv) {
+          const name = String(raw ?? '').trim()
+          if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+            requiredEnvError = `contains invalid name ${name || '(empty)'}`
+            break
+          }
+          if (names.has(name)) {
+            requiredEnvError = `contains duplicate name ${name}`
+            break
+          }
+          names.add(name)
+        }
+      }
+
+      const healthCheck = manifest.healthCheck
+      if (healthCheck !== undefined) {
+        if (!isRecord(healthCheck)) {
+          healthError = 'must be an object'
+        } else {
+          const allowedHealthFields = new Set([
+            'enabled',
+            'path',
+            'timeoutMs',
+            'retries',
+          ])
+          const unsupportedHealthField = Object.keys(healthCheck).find(
+            (field) => !allowedHealthFields.has(field),
+          )
+          if (unsupportedHealthField) {
+            healthError = `contains unsupported field ${unsupportedHealthField}`
+          } else if (
+            healthCheck.enabled !== undefined &&
+            healthCheck.enabled !== true
+          ) {
+            healthError = 'enabled must be true when present'
+          } else if (
+            healthCheck.path !== undefined &&
+            healthCheck.path !== '/api/health'
+          ) {
+            healthError = 'path must be /api/health when present'
+          } else if (healthCheck.timeoutMs !== undefined) {
+            const timeoutMs = Number(healthCheck.timeoutMs)
+            if (
+              !Number.isFinite(timeoutMs) ||
+              timeoutMs < 500 ||
+              timeoutMs > 30_000
+            ) {
+              healthError = 'timeoutMs must be between 500 and 30000'
+            }
+          }
+          if (!healthError && healthCheck.retries !== undefined) {
+            const retries = Number(healthCheck.retries)
+            if (!Number.isInteger(retries) || retries < 1 || retries > 60) {
+              healthError = 'retries must be an integer between 1 and 60'
+            }
+          }
+        }
+      }
+    }
+
+    if (manifestErrors.length > 0) {
+      failures.push(`deploy.json manifest ${manifestErrors.join('; ')}`)
+    }
+    if (requiredEnvError) {
+      failures.push(
+        `deploy.json.requiredEnv ${requiredEnvError}; generated default is ${releaseRequiredEnvKeys.join(', ')}`,
+      )
+    }
+    if (healthError) {
+      failures.push(`deploy.json.healthCheck ${healthError}`)
+    }
+  } catch (error) {
+    failures.push(`deploy.json: ${String(error)}`)
+  }
+}
+
 for (const file of requiredFiles) {
   if (!(await exists(file))) failures.push(`missing ${file}`)
 }
@@ -1260,12 +1410,21 @@ if (await exists('src/styles.css')) {
 }
 
 if (await exists('.env.example')) {
-  const values = parseEnv(
-    await readFile(path.join(root, '.env.example'), 'utf8'),
-  )
+  const exampleSource = await readFile(path.join(root, '.env.example'), 'utf8')
+  const values = parseEnv(exampleSource)
   for (const key of requiredEnvKeys) {
     if (!values.has(key)) failures.push(`.env.example missing ${key}`)
   }
+  if (!exampleSource.includes(optionalEnvExampleMarker)) {
+    failures.push(
+      `.env.example missing optional resource fallback example: ${optionalEnvExampleMarker}`,
+    )
+  }
+  if (values.has('REALSEE_DEFAULT_RESOURCE_CODE')) {
+    failures.push(
+      '.env.example must keep REALSEE_DEFAULT_RESOURCE_CODE commented as optional',
+    )
+  }
   for (const [key, value] of values) {
     if (key.startsWith('VITE_WORK_'))
       failures.push(
@@ -1312,7 +1471,13 @@ if (await exists('.gitignore')) {
 for (const [relativePath, markers] of [
   [
     'server/types.ts',
-    ['ServerConfig', 'WorkEnvelope', 'WorkDetailClient', 'WorkService'],
+    [
+      'ServerConfig',
+      'WorkEnvelope',
+      'WorkDetailClient',
+      'WorkService',
+      'defaultResourceCode: string | undefined',
+    ],
   ],
   [
     'server/config.ts',
@@ -1321,6 +1486,9 @@ for (const [relativePath, markers] of [
       'REALSEE_GATEWAY_APP_KEY',
       'REALSEE_GATEWAY_APP_SECRET',
       'REALSEE_DEFAULT_RESOURCE_CODE',
+      'optionalResourceCode',
+      'if (!nonEmptyString(value)) return undefined',
+      '^[A-Za-z0-9_-]{1,128}$',
       "gatewayEndpoint.protocol !== 'https:'",
       '): ServerConfig {',
     ],
@@ -1357,6 +1525,8 @@ for (const [relativePath, markers] of [
     [
       "'/api/work'",
       "'/api/work/:resourceCode'",
+      'defaultResourceCode: string | undefined',
+      "error: 'RESOURCE_CODE_REQUIRED'",
       'getWorkByResourceCode(resourceCode, {',
       'signal: requestAbort.signal',
       'WORK_UPSTREAM_FAILED',
@@ -1367,6 +1537,7 @@ for (const [relativePath, markers] of [
     [
       'Fastify({ logger })',
       "'/api/health'",
+      'defaultResourceCode: string | undefined',
       'fastifyStatic',
       'serveFrontend',
       "reply.sendFile('index.html')",

package/templates/base/.env.example

@@ -8,7 +8,7 @@ REALSEE_GATEWAY_ENDPOINT=https://app-gateway.realsee.cn
 REALSEE_GATEWAY_APP_KEY=*
 # Realsee 的网关 app secret
 REALSEE_GATEWAY_APP_SECRET=*
-# 首次运行时默认加载的 VR ID（resourceCode）
-REALSEE_DEFAULT_RESOURCE_CODE=*
+# 可选的根路由 fallback VR ID（resourceCode）；未配置时请使用 /{resourceCode}
+# REALSEE_DEFAULT_RESOURCE_CODE=example-resource-code
 # Realsee 的企业账号 ID（可选部署元数据）
 REALSEE_SOURCE=REALSEE_TECH

package/templates/base/.gitignore.template

@@ -1,6 +1,8 @@
 node_modules/
 dist/
+/release/
 .env*
 !.env.example
+.realsee/
 *.log
 .DS_Store

package/templates/base/.prettierignore

@@ -1,5 +1,7 @@
 node_modules/
 dist/
+release/
+.tmp-*
 .agents/
 .claude/
 .cursor/

package/templates/base/README.md

@@ -14,14 +14,27 @@ Use Node.js `22.23.2` LTS from `.nvmrc` and `.node-version`: it is the current s
 npm ci
 npm run setup
 npm run dev
-# Open http://127.0.0.1:8087/.
+# Open http://127.0.0.1:8087/{resourceCode}.
 ```
 
-`npm run setup` accepts exactly one versioned single-line payload copied from the Realsee China Portal onboarding page. Paste it only into the hidden interactive prompt. The payload contains AK, SK and the selected `resourceCode`; Base64URL is a cross-platform transport encoding, not encryption. Never put it in chat, command arguments, pipes, redirected input, shell history, source or logs. Setup writes the gitignored server-only `.env.development` atomically with `0600` on POSIX or a current-user ACL on Windows.
+`npm run setup` pairs this machine with the Realsee China Portal: it prints a verification link and an `XXXX-XXXX` short code, the user confirms the request in the browser, and the command polls until the server reports a terminal state before writing the gitignored server-only `.env.development`. Agents and harnesses that only see a command's final output must use the split flow instead:
+
+Each local project receives a stable, random `project_instance_id` on its first pairing attempt. It is stored in the gitignored `.realsee/project.json` and is not a credential. The Portal shows the project name, the first eight characters of this ID, and the requesting machine in the existing `client_name` field so that same-name projects can be distinguished. Do not copy `.realsee/` into source control or a release package.
+
+```bash
+npm run setup -- --no-wait --json   # prints {ok:true,data:{status:"pending",...}} and exits 2
+npm run setup -- --complete         # after the user confirms; polls, writes .env.development
+```
+
+`poll_secret` is never printed: it stays in process memory and in the `0600`, gitignored `.realsee/pairing-continuation.json`. The split-flow pending result includes non-sensitive `client_name` and `replacing_config` so an AI assistant can identify the current project and warn before replacement. Success prints `{"ok":true,...}` on stdout — judge it with `ok===true`, never a `code` field — and only a masked AK ever appears in output. Failures print `{"ok":false,"error":{code,message,hint}}` on stderr with exit code `0` written, `2` pending, `3` denied (never re-sent automatically), `4` expired, `5` service unavailable, `1` otherwise.
+
+`REALSEE_GATEWAY_APP_KEY`/`REALSEE_GATEWAY_APP_SECRET` environment variables (CI, unattended installs) take precedence over both paths and skip pairing. The fallback `npm run setup -- --paste` keeps the hidden-input path for exactly one versioned single-line payload copied from the Portal spatial app creation page: the payload always contains AK/SK and may also contain an optional selected `resourceCode` fallback; existing three-field v1 payloads remain supported. Base64URL is a cross-platform transport encoding, not encryption. Never put it in chat, command arguments, pipes, redirected input, shell history, source or logs. Setup writes the file atomically with `0600` on POSIX or a current-user ACL on Windows, and omits `REALSEE_DEFAULT_RESOURCE_CODE` when no fallback is supplied.
+
+To change the organization, Developer App, credentials, or default VR in this project, run `npm run setup` again and confirm the new request in the Portal. Successful setup replaces only this project's `.env.development`; a denied or expired request leaves the existing file unchanged. Restart `npm run dev` afterward. Other local projects have independent configuration and project IDs.
 
 `REALSEE_GATEWAY_ENDPOINT` must be an HTTPS URL; the BFF refuses HTTP so AK/SK cannot be sent in cleartext. `npm run dev` validates `.env.development` before starting Fastify and Vite. After changing `.env.development`, stop the existing dev command and start it again so Node reloads the environment.
 
-Development runs the Fastify BFF on `127.0.0.1:8088` and Vite on `127.0.0.1:8087`; Vite proxies `/api` to Fastify, so onboarding uses the same-origin `GET /api/work` contract backed by `REALSEE_DEFAULT_RESOURCE_CODE`. The explicit `GET /api/work/{resourceCode}` and `/{resourceCode}` paths remain development-only compatibility routes. Port 8087 is non-privileged; do not change it to privileged port 517.
+Development runs the Fastify BFF on `127.0.0.1:8088` and Vite on `127.0.0.1:8087`; Vite proxies `/api` to Fastify. The canonical Work route is `GET /api/work/{resourceCode}`, reached from `/{resourceCode}`. The root `/` route calls `GET /api/work`: it uses `REALSEE_DEFAULT_RESOURCE_CODE` only when that optional fallback is configured, otherwise it returns the controlled `RESOURCE_CODE_REQUIRED` 400 response without calling upstream. Port 8087 is non-privileged; do not change it to privileged port 517.
 
 The BFF posts `REALSEE_GATEWAY_APP_KEY` and `REALSEE_GATEWAY_APP_SECRET` as form fields to `/auth/access_token`, caches the 5-minute token until shortly before `expire_at`, retries once after an upstream 401, then calls `GET /open/v3/vr/info?resource_code={resourceCode}` with the raw token in the `Authorization` header. It returns only the browser-safe `{ work, workCode, baseURL? }` envelope. Generic `tags` are not inferred as PanoTag data. The default gateway is `https://app-gateway.realsee.cn`; overseas deployments use `https://app-gateway.realsee.jp`. See the official [Realsee OpenAPI reference](https://open-platform.realsee.com/developer/openapi/?id=1001).
 
@@ -32,9 +45,21 @@ npm run build
 npm start
 ```
 
+## Package for Vibe Release
+
+Create the source ZIP accepted by Vibe Release with the project-local command:
+
+```bash
+npm run package:vibe-release
+```
+
+The command runs a clean `npm ci` and the canonical production build, then writes `release/<package-name>-node-vite-bff-v1.zip`. The ZIP contains source files at its root and intentionally excludes local `node_modules`, `dist`, release output, `.env*`, credentials, logs, and editor/Agent state. Vibe Release rebuilds `dist` in Linux.
+
+`deploy.json` declares required runtime variable names only. The generated default requires exactly `REALSEE_GATEWAY_APP_KEY` and `REALSEE_GATEWAY_APP_SECRET`; `REALSEE_DEFAULT_RESOURCE_CODE` is an optional root-route fallback and belongs in `requiredEnv` only when an application deliberately makes it mandatory. Configure declared values in Vibe Release settings; never write AK/SK or resource values into the ZIP.
+
 ## Replace the example BFF
 
-The browser onboarding path depends on `GET /api/work`; Fastify is an example implementation, not an application architecture requirement:
+The browser always supports the explicit `GET /api/work/{resourceCode}` contract; `GET /api/work` is only the optional fallback form. Fastify is an example implementation, not an application architecture requirement:
 
 - `server/types.ts` declares the server-side contracts (`ServerConfig`, `WorkEnvelope`, `WorkDetailClient`, `WorkService`);
 - `server/realsee-open-api.ts` owns Realsee token exchange, expiry caching and upstream Work calls;
@@ -51,7 +76,7 @@ The generated project has one `.env.example`. Only the Fastify BFF reads `REALSE
 
 ## Update dependencies
 
-The manifest intentionally declares every direct dependency except `three` as an open minimum range (`>=baseline`). The committed `package-lock.json` records the generator's reviewed initial resolution, so `npm ci` remains reproducible while an explicit update can move across major versions.
+The manifest intentionally declares application/runtime dependencies and ordinary development dependencies as open minimum ranges (`>=baseline`), except for version-bound Three. The release-only `adm-zip` tool is an additional exact-pinned development dependency because archive bytes and APIs must not drift between clean packaging runs. The committed `package-lock.json` records the generator's reviewed initial resolution, so `npm ci` remains reproducible while an explicit application dependency update can move across major versions.
 
 To update every unlocked dependency to the newest release allowed by its open range:
 
@@ -71,9 +96,10 @@ npm run build
 
 `.npmrc` uses `save-prefix=>=`, so newly saved direct dependencies and explicit upgrades retain the open-minimum policy. After manually editing a minimum, use `npm run deps:relock`, then `npm run deps:install` to verify a clean lockfile install.
 
-Only one dependency is hard-locked:
+Two dependencies are exact-pinned for different boundaries:
 
 - `three` must stay exactly `0.117.1`. Five 6.8.9 targets that release, and the generated code plus the bundled Three capability references assume the r117 API surface. `vr-cli doctor` and the portable verifier reject any other value, including ranges.
+- `adm-zip` must stay exactly `0.6.0`. It is used only by `npm run package:vibe-release`; `vr-cli doctor` rejects archive-tool drift so clean release output is produced by the reviewed implementation.
 - Every other dependency, including `@realsee/five`, `@realsee/dnalogel`, `@realsee/vapor`, Fastify, React, Vite, TypeScript and the lint stack, must use `>=x.y.z` with a minimum no lower than the generator baseline. Exact, caret, tilde and bounded ranges are rejected because they cannot move freely to the latest release.
 - The lockfile's resolved direct version must satisfy both the declared minimum and the generator baseline. Raising a minimum requires relocking.
 

package/templates/base/deploy.json

@@ -0,0 +1,11 @@
+{
+  "packageFormat": "node-vite-bff-v1",
+  "name": "{{PACKAGE_NAME}}",
+  "requiredEnv": ["REALSEE_GATEWAY_APP_KEY", "REALSEE_GATEWAY_APP_SECRET"],
+  "healthCheck": {
+    "enabled": true,
+    "path": "/api/health",
+    "timeoutMs": 2500,
+    "retries": 15
+  }
+}

package/templates/base/eslint.config.mjs

@@ -10,6 +10,8 @@ export default tseslint.config(
     ignores: [
       'node_modules/**',
       'dist/**',
+      'release/**',
+      '.tmp-*',
       '.agents/**',
       '.claude/**',
       '.cursor/**',