@jay-framework/jay-stack-cli 0.25.3 → 0.25.5

package/agent-kit-template/devops/INSTRUCTIONS.md

@@ -35,24 +35,28 @@ When running `jay-stack-cli setup` without `--interactive`, plugins that need us
 
 ```yaml
 setup-needs-answer:
-  plugin: wix-server-client
-  key: api-key
+  plugin: '@jay-framework/some-plugin'
+  key: apiKey
   type: input
   message: 'Enter your API key'
+  choices: # present only for select-type questions
+    - us: United States
 ```
 
-To provide the answer, create a YAML file and re-run:
+To provide the answer, create a YAML file keyed by the `key` field and re-run:
 
 ```yaml
 # answers.yaml
-api-key: 'IST.abc123...'
+apiKey: 'your-answer'
 ```
 
 ```bash
 jay-stack-cli setup --answers answers.yaml
 ```
 
-Repeat until all plugins report `configured`. The flow is iterative — each run may reveal the next question.
+Repeat until all plugins report `configured`. The flow is iterative — each run may reveal the next question. The `key` is the stable join field between a question and its answer.
+
+> **Exception — Wix login is not answerable via a file.** The Wix plugins' credential setup shells out to the Wix CLI for a browser-based OAuth login (`npx @wix/cli login`). In non-interactive mode it reports `needs-config` ("requires interactive mode") rather than a `setup-needs-answer:` — there is no key you can put in `answers.yaml`. A human must run `jay-stack-cli setup --interactive` in a real terminal once; after that the app secret, client ID, and site ID are fetched/derived automatically. `wix-deploy` also needs a live Wix CLI session at deploy time (`jay-stack run wix-deploy/deploy`) — re-run `npx @wix/cli login` if it reports the session is missing.
 
 ### Setup order
 
@@ -64,6 +68,68 @@ jay-stack-cli agent-kit          # 2. Generate contracts and discovery data
 jay-stack-cli build              # 3. Production build
 ```
 
+## Running in cloud / remote environments
+
+Running the dev server behind a cloud preview proxy (sandboxes, Codespaces, Gitpod, etc.) has three
+non-obvious requirements.
+
+### 1. Allow the proxy's host (Vite host check)
+
+The dev server runs Vite in middleware mode, and Vite's host check 403s any request whose `Host` header
+isn't `localhost` ("Blocked request. This host is not allowed."). Allow the external host via `.jay`:
+
+```yaml
+# .jay
+devServer:
+  allowedHosts:
+    - .mysandbox.dev # Vite host-suffix syntax — matches any subdomain
+  # or, to disable the check entirely (dev only):
+  # allowedHosts: true
+```
+
+Platforms that already set Vite's `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` env var (comma-separated
+hosts, or `true`) need **no** `.jay` change — the dev server reads and merges it. Do **not** add a
+`src/pages/vite.config.ts` to work around this; use the config above (DL#220).
+
+> HMR over a proxy may additionally need Vite's `server.hmr` client settings — not required for serving
+> pages, only for live reload through the proxy.
+
+### 2. Binding and port
+
+`jay-stack-cli dev` takes **no** `--port` / `--host` flags. The Express server binds all interfaces, so
+the container is reachable as-is; set the port in `.jay` (`devServer.portRange`, e.g. `[3000, 3000]` to
+pin it).
+
+### 3. Credentials are read from files, not env vars
+
+Plugins read credentials from files written by `setup`, not from `process.env`. Wix, for example, uses
+`config/.wix.yaml` (backend services) and `wix.config.json` (deploy target) — both gitignored. A
+container that only has secrets as env vars must **materialize them into those files before** starting
+the dev server (e.g. a startup script that writes `config/.wix.yaml` from `WIX_*` env vars). Putting
+`WIX_*` under a compose `environment:` block does **not** configure the plugins.
+
+### 4. AIditor (visual editor) in a container
+
+The `/aiditor` route runs an agent **server-side** via the Claude Agent SDK, so the environment running
+the dev server — not the user's laptop — must have Claude Code available:
+
+- **Install the `claude` CLI in the image.** It is not part of the Node base image.
+- **Provide `ANTHROPIC_API_KEY` as a secret/env var.** `claude login` is interactive and cannot complete
+  headless, so in a container the API key is the only viable auth. (Locally, `claude login` also works.)
+- **It's dev-only.** The `/aiditor` route is served by the dev server; it is excluded from production
+  deploy (`--exclude-plugins aiditor`). If you don't need visual editing in a given environment, you can
+  ignore it — the rest of the site scaffolds, builds, runs, and deploys without it; only the `/aiditor`
+  route's agent stays inert when the CLI/key are absent.
+
+A cloud platform that boots the dev server but neither installs the CLI nor injects the key will serve a
+working site with a non-functional `/aiditor` — the single most common surprise. Install both, or
+document that visual editing is unavailable there.
+
+### Health / shutdown (containers)
+
+Run with `--test-mode` to expose `GET /_jay/health` (readiness probe) and `POST /_jay/shutdown` (graceful
+stop) — the sanctioned hooks for container healthchecks and lifecycle, instead of signal-guessing.
+
 ## Guides
 
 | File                                       | Topic                                                      |

package/dist/{index-B5oavmfA.js → index-_Gyf630q.js}

@@ -486,6 +486,10 @@ async function loadProductionPageParts(route, pageModule, jayHtmlContent, projec
       const ci = headlessImport.contract ? { contractName: headlessImport.contract.name, metadata: headlessImport.metadata } : void 0;
       parts.push({
         key: headlessImport.key,
+        // DL#221 post-merge fix: the component's module is its global identity — keys the
+        // build-time loadParams cache so two routes reusing the same ref `key` for different
+        // components don't collide (the ref `key` is page-local).
+        modulePath,
         compDefinition: headlessCompDef,
         clientImport: "",
         clientPart: "",
@@ -823,6 +827,11 @@ async function parseViteManifest(outputDir, packages) {
   await fs.rm(viteManifestPath, { force: true });
   return manifest;
 }
+function loadParamsCacheKey(rawRoute, part) {
+  const propsKey = JSON.stringify(part.headlessProps ?? {});
+  if (part.key) return `headless:${part.modulePath ?? part.key}:${propsKey}`;
+  return `page:${rawRoute}:${propsKey}`;
+}
 function crossProductParams(parts) {
   if (parts.length === 0) return [];
   if (parts.length === 1) return parts[0].values;
@@ -1487,8 +1496,7 @@ async function buildVersion(options) {
     if (partsWithLoadParams.length === 0) continue;
     const paramParts = [];
     for (const part of partsWithLoadParams) {
-      const propsKey = JSON.stringify(part.headlessProps ?? {});
-      const cacheKey = `${part.key ?? ""}:${propsKey}`;
+      const cacheKey = loadParamsCacheKey(route.rawRoute, part);
       if (!loadParamsCache.has(cacheKey)) {
         logger.important(`[Build] Loading params for ${route.rawRoute}...`);
         const partParams = [];
@@ -1796,6 +1804,7 @@ export {
   discoverActions,
   discoverServerEntries,
   generateRouteHydrationEntry,
+  loadParamsCacheKey,
   loadProductionPageParts,
   materializeRouteParams,
   scanPluginRoutes,

package/dist/index.d.ts

@@ -25,6 +25,20 @@ interface JayConfig {
         componentsBase?: string;
         publicFolder?: string;
         configBase?: string;
+        /**
+         * Hosts the dev server's Vite host-check accepts, beyond localhost. Use Vite's host-suffix
+         * syntax (`.example.dev` matches any subdomain), or `true` to disable the check entirely
+         * (dev only — e.g. cloud preview sandboxes). Merged with the
+         * `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS` env var. Absent → Vite's localhost-only default.
+         * (DL#220)
+         */
+        allowedHosts?: string[] | true;
+        /**
+         * Inject source-editing dev markers (`jay-dev-src` / `jay-dev-item`) so the source-editing
+         * inspector can map a rendered pixel back to its jay-html source (DL#219). Off by default —
+         * the markers change rendered output, so enable only for AIditor / source-editing sessions.
+         */
+        sourceEditing?: boolean;
     };
     site?: {
         baseUrl?: string;

package/dist/index.js

@@ -65,7 +65,11 @@ function getConfigWithDefaults(config) {
       pagesBase: config.devServer?.pagesBase || DEFAULT_CONFIG.devServer.pagesBase,
       componentsBase: config.devServer?.componentsBase || DEFAULT_CONFIG.devServer.componentsBase,
       publicFolder: config.devServer?.publicFolder || DEFAULT_CONFIG.devServer.publicFolder,
-      configBase: config.devServer?.configBase || DEFAULT_CONFIG.devServer.configBase
+      configBase: config.devServer?.configBase || DEFAULT_CONFIG.devServer.configBase,
+      // No default — absent means Vite's localhost-only host check (DL#220).
+      allowedHosts: config.devServer?.allowedHosts,
+      // Default off — source-editing markers (DL#219) only for opt-in sessions.
+      sourceEditing: config.devServer?.sourceEditing
     },
     site: config.site
   };
@@ -220,7 +224,9 @@ async function startDevServer(options = {}) {
     publicBaseUrlPath: "/",
     jayRollupConfig: jayOptions,
     logLevel: options.logLevel,
-    httpServer
+    httpServer,
+    allowedHosts: resolvedConfig.devServer.allowedHosts,
+    sourceEditing: resolvedConfig.devServer.sourceEditing
   });
   app.use(server);
   const publicPath = path$1.resolve(resolvedConfig.devServer.publicFolder);
@@ -7548,7 +7554,7 @@ async function runBuild(projectPath, options) {
   }
   const ctx = await resolveProductionContext(projectPath, options.version);
   await generateDefinitionFiles(ctx);
-  const { buildVersion } = await import("./index-B5oavmfA.js");
+  const { buildVersion } = await import("./index-_Gyf630q.js");
   await buildVersion({
     version: ctx.version,
     projectRoot: ctx.resolvedPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.25.3",
+  "version": "0.25.5",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -25,18 +25,18 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@jay-framework/compiler-inline-composition": "^0.25.3",
-    "@jay-framework/compiler-jay-html": "^0.25.3",
-    "@jay-framework/compiler-shared": "^0.25.3",
-    "@jay-framework/dev-server": "^0.25.3",
-    "@jay-framework/fullstack-component": "^0.25.3",
-    "@jay-framework/logger": "^0.25.3",
-    "@jay-framework/plugin-validator": "^0.25.3",
-    "@jay-framework/production-build": "^0.25.3",
-    "@jay-framework/production-server": "^0.25.3",
-    "@jay-framework/stack-route-scanner": "^0.25.3",
-    "@jay-framework/stack-server-build": "^0.25.3",
-    "@jay-framework/stack-server-runtime": "^0.25.3",
+    "@jay-framework/compiler-inline-composition": "^0.25.5",
+    "@jay-framework/compiler-jay-html": "^0.25.5",
+    "@jay-framework/compiler-shared": "^0.25.5",
+    "@jay-framework/dev-server": "^0.25.5",
+    "@jay-framework/fullstack-component": "^0.25.5",
+    "@jay-framework/logger": "^0.25.5",
+    "@jay-framework/plugin-validator": "^0.25.5",
+    "@jay-framework/production-build": "^0.25.5",
+    "@jay-framework/production-server": "^0.25.5",
+    "@jay-framework/stack-route-scanner": "^0.25.5",
+    "@jay-framework/stack-server-build": "^0.25.5",
+    "@jay-framework/stack-server-runtime": "^0.25.5",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -47,7 +47,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.25.3",
+    "@jay-framework/dev-environment": "^0.25.5",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",