@jskit-ai/agent-docs 0.1.83 → 0.1.85

package/guide/agent/app-setup/authentication.md

@@ -961,39 +961,40 @@ That explains why the login screen and auth guard runtime both care about `/api/
 
 It is also why the shell widget can react cleanly to auth state without storing raw session tokens in client state. The browser just asks the app for the current session view, and the app derives that from its cookies plus the selected provider.
 
-### Authenticated Playwright testing with the dev auth bypass
+### Authenticated Playwright testing
 
-JSKIT ships a development-only auth bootstrap path specifically so authenticated UI can be verified in Playwright without depending on a real live login flow through an external auth provider.
+JSKIT supports two intentionally separate authenticated-browser paths:
 
-This is the standard path the agent should use for authenticated browser tests:
+- a private localhost exchange for direct local Playwright runs
+- runner-provided Playwright storage state for managed previews
 
-- enable the dev auth bypass in development
-- create a session for an existing user through the local app
-- let the browser keep the resulting HTTP-only cookies
-- navigate to the protected page and verify the feature
-- record the Playwright run through `jskit app verify-ui` so `jskit doctor` can verify the receipt later
+Neither path drives a live external login provider. Both put the resulting HTTP-only cookies into the same Playwright browser context that runs the feature assertions.
 
-The feature is intentionally narrow.
+The generated `playwright.config.mjs` is a thin delegate to `@jskit-ai/jskit-cli/test/playwright`. The published helper owns the changing setup behavior:
 
-- It is development-only.
-- It must never be enabled in production.
-- JSKIT rejects boot if `AUTH_DEV_BYPASS_ENABLED=true` while `NODE_ENV=production`.
-- The route only looks up an existing user. It does not create one.
+- without `PLAYWRIGHT_BASE_URL`, it builds the app and starts the local server on `http://127.0.0.1:4173`
+- with `PLAYWRIGHT_BASE_URL`, it uses that managed preview and does not start another server
+- with `JSKIT_PLAYWRIGHT_STORAGE_STATE`, it loads the supplied authenticated state into Playwright contexts
 
-The environment variables are:
+Tests should therefore navigate with relative paths such as `page.goto("/w/acme/admin/contacts")`.
+
+#### Direct local dev-auth login
+
+The local dev auth bypass remains deliberately narrow:
+
+- it is available only outside production
+- the request must arrive locally
+- it selects an existing user and never creates one
+- it requires both CSRF protection and a private exchange secret
+
+Enable it for the Playwright process and the local server it starts:
 
 ```bash
 AUTH_DEV_BYPASS_ENABLED=true
 AUTH_DEV_BYPASS_SECRET=replace-this-with-a-local-dev-secret
 ```
 
-When enabled outside production, the app exposes:
-
-```text
-POST /api/dev-auth/login-as
-```
-
-The request body must contain either:
+When enabled, the app exposes `POST /api/dev-auth/login-as`. The body contains exactly one existing-user identity:
 
 ```json
 { "userId": "7" }
@@ -1005,70 +1006,45 @@ or:
 { "email": "ada@example.com" }
 ```
 
-The response is intentionally small:
+Do not call that route from `page.evaluate()`. The route requires the private `x-jskit-dev-auth-secret` header as well as the CSRF token. Putting the secret into browser JavaScript, client-visible environment, query parameters, or page globals would defeat the exchange boundary.
 
-```json
-{
-  "ok": true,
-  "userId": "7",
-  "username": "Ada Example",
-  "email": "ada@example.com"
-}
-```
+Use the published Node-side helper instead:
 
-Behind the scenes, JSKIT creates the same HTTP-only auth cookies that the normal login flow would create. That means Playwright should not try to read raw tokens. It should bootstrap the session in the browser context, then navigate normally.
+```ts
+import { expect, test } from "@playwright/test";
+import { loginAsExistingUser } from "@jskit-ai/auth-web/test/playwright";
 
-One subtle point matters here:
+test("authenticated contacts filters", async ({ page }) => {
+  await loginAsExistingUser(page, { email: "ada@example.com" });
 
-- `/api/dev-auth/login-as` is still an unsafe `POST`
-- JSKIT still expects a CSRF token
-- the browser can get that token from `/api/session`
+  await page.goto("/w/acme/admin/contacts");
+  await expect(page.getByRole("heading", { name: "Contacts" })).toBeVisible();
+});
+```
 
-So the normal Playwright shape is:
+`loginAsExistingUser()` runs from the Playwright Node process. It uses the request client attached to `page.context()`, reads `csrfToken` from `GET /api/session`, sends that token plus `x-jskit-dev-auth-secret` to the login route, and leaves the response cookies in the same browser context. It reads `AUTH_DEV_BYPASS_SECRET` from the Node process by default and refuses to send it to a non-local URL.
 
-1. open a same-origin page first
-2. call `/api/session` to read `csrfToken`
-3. call `/api/dev-auth/login-as` with `credentials: "include"` and the `csrf-token` header
-4. navigate to the protected route and run the assertions
+That last restriction is important. A managed preview URL is not a direct localhost app connection, even when its backend eventually runs on the same infrastructure. Project code must not receive the managed host's private exchange authority.
 
-For example:
+#### Managed preview authentication
 
-```ts
-await page.goto("/");
+A managed host authenticates outside the project browser context. It performs its trusted identity exchange, writes the resulting cookies and origins to a temporary Playwright storage-state file, and starts the project test with:
 
-await page.evaluate(async ({ email }) => {
-  const sessionResponse = await fetch("/api/session", {
-    credentials: "include"
-  });
-  if (!sessionResponse.ok) {
-    throw new Error(`Session bootstrap failed: ${sessionResponse.status}`);
-  }
+```bash
+PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
+JSKIT_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+playwright test tests/e2e/contacts.spec.ts
+```
 
-  const sessionPayload = await sessionResponse.json();
-  const csrfToken = String(sessionPayload?.csrfToken || "");
-  if (!csrfToken) {
-    throw new Error("Missing csrfToken from /api/session.");
-  }
+JSKIT only consumes that runner-neutral contract. It does not detect a particular host, call host-specific commands, proxy private headers, or install a browser.
 
-  const loginResponse = await fetch("/api/dev-auth/login-as", {
-    method: "POST",
-    credentials: "include",
-    headers: {
-      "content-type": "application/json",
-      "csrf-token": csrfToken
-    },
-    body: JSON.stringify({ email })
-  });
+The storage-state file is a secret because it can contain authenticated cookies. The managed runner must create it with appropriately restricted access, must not print or commit it, and must delete it after the run.
 
-  if (!loginResponse.ok) {
-    throw new Error(`Dev login failed: ${loginResponse.status} ${await loginResponse.text()}`);
-  }
-}, { email: "ada@example.com" });
+Tests using managed state do not call `loginAsExistingUser()`. They begin with the runner-provided identity already present and navigate using relative paths. An ordinary browser or proxy request to `/api/dev-auth/login-as` without the private header must continue to fail with `403 Dev auth exchange is not authorized.`
 
-await page.goto("/w/acme/admin/contacts");
-```
+#### Recording the result
 
-In practice, the preferred wrapper is:
+After the actual Playwright flow succeeds, record it through JSKIT:
 
 ```bash
 npx jskit app verify-ui \
@@ -1077,20 +1053,17 @@ npx jskit app verify-ui \
   --auth-mode dev-auth-login-as
 ```
 
-For local pre-merge review, the next step after recording that Playwright run is usually:
+Use `--auth-mode session-bootstrap` when a managed runner supplied authenticated storage state.
+
+`jskit app verify-ui` executes the command and records the command, auth-mode label, feature, and changed UI files. The `--auth-mode` value describes how the Playwright command was authenticated. It does not create a session, inject a secret, or alter the browser context.
+
+For local pre-merge review, follow the recorded run with:
 
 ```bash
 npx jskit doctor --against origin/main
 ```
 
-Advanced CI pipelines can use the same `--against` contract too, but JSKIT does not scaffold hosted auth/database/browser verification by default.
-
-That flow is preferable to driving the real sign-in form in feature tests because it keeps the test focused on the UI feature being added, not on an external auth dependency. If a chunk changes user-facing UI and the flow requires login, the expected JSKIT review standard is:
-
-- use Playwright
-- record the run with `jskit app verify-ui`
-- use the local dev auth bypass or another local session bootstrap path
-- exercise the actual changed behavior, not only page load
+This keeps feature tests focused on the changed UI while preserving the security boundary around session creation.
 
 ## When you later switch to Supabase
 

package/guide/agent/app-setup/initial-scaffolding.md

@@ -210,6 +210,8 @@ Published JSKIT libraries and tooling support Node.js 22 from 22.12.0 onward, No
 
 That matters because JSKIT maintenance policy changes over time. If the scaffold copied a large shell script into every app, existing apps would freeze the old behavior forever. By delegating to `jskit app verify`, `jskit app update-packages`, `jskit app link-local-packages`, and `jskit app release`, the app keeps the nice `npm run` shortcuts while the maintained behavior stays in the installed CLI package.
 
+The Playwright scaffold follows the same rule. `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`, and the starter browser specs delegate their shared responsive checks to published JSKIT helpers. The generated files stay small while later JSKIT package updates can change local server startup, managed `PLAYWRIGHT_BASE_URL` handling, and `JSKIT_PLAYWRIGHT_STORAGE_STATE` support without copying that logic into each new app.
+
 `jskit app verify` is worth noticing specifically. Linting, tests, and builds check your source code and runtime behavior. The JSKIT part of that flow runs `doctor`, which checks JSKIT-managed app state: installed package visibility, lock-file-backed managed files, and other JSKIT-specific health rules. It is there because a JSKIT app is not only code. It is also a descriptor-driven managed project.
 
 The starter scaffold also writes `.github/workflows/jskit-verify.yml`. JSKIT generates and owns that workflow as a projection of installed package `ci` contracts. The baseline runs checkout, Node 26 setup, `npm ci`, and `npm run verify`. Packages can add job environment values, service containers, and explicit `before-verify` steps without taking ownership of the whole YAML file. For example, the database runtime adds migrations before verification. Its MySQL driver adds a MariaDB service with synthetic CI-only credentials and `DB_CLIENT=mysql2`; its Postgres driver adds the equivalent Postgres service and `DB_CLIENT=pg`.

package/guide/agent/app-setup/working-with-the-jskit-cli.md

@@ -106,6 +106,25 @@ npm run release -- --registry https://registry.example.com
 
 When the app declares npm workspaces, the command asks npm for the workspace graph and aligns JSKIT references in each workspace `package.json` and `package.descriptor.mjs` to the latest major range, such as `0.x`. Descriptor dependency mutations are included whether they use a direct string or a conditional `{ version, when }` record. It then runs `npm update --workspaces` for those packages so `package-lock.json` reflects the aligned ranges. Non-JSKIT dependencies and the public descriptor format are left alone.
 
+Updating npm packages is only half of a JSKIT upgrade. Package descriptors also own managed files, source and text mutations, lock metadata, migrations, and CI contributions. After installing newer root packages, `update-packages` compares their target versions with the installed records in `.jskit/lock.json`. It reapplies each changed installed package through the same `jskit update package ...` lifecycle used for a manual update. The newly installed local CLI performs that work, saved package options are reused, and customized app-owned files remain protected by the normal ownership checks. The updater reloads the lock between packages, so a dependency already upgraded while reapplying another package is not applied twice.
+
+This means the normal existing-app upgrade is one command:
+
+```bash
+npm run jskit:update
+```
+
+After it succeeds, npm dependencies and descriptor-managed app state are current together. If a managed app-owned file is missing, a required saved option can no longer be resolved, or another package update cannot be applied safely, the app-wide update fails instead of leaving that package silently stale. `--dry-run` reports which installed packages would be reapplied without invoking their update lifecycle.
+
+There is one unavoidable bootstrap detail for apps whose installed CLI predates managed package reapplication: a CLI process that is already running cannot adopt code npm installs underneath it. Upgrade the CLI once, then run the app-wide update with the new process:
+
+```bash
+npm install --save-dev --save-exact @jskit-ai/jskit-cli@latest
+npm run jskit:update
+```
+
+After that bootstrap, normal future upgrades use only `npm run jskit:update`. Do not work around the first upgrade by editing `.jskit/lock.json`; the new updater must reapply the descriptor contract and write managed state itself.
+
 The update reports elapsed progress for registry and install work. It also refreshes JSKIT-managed migrations and CI after root package changes. Preview the complete operation without changing manifests, descriptors, the lockfile, migrations, or CI with:
 
 ```bash
@@ -781,7 +800,7 @@ Good times to run it manually include:
 - when a package appears installed in the lock but starts behaving as if it is missing
 - when you want a fast JSKIT-specific health check without waiting for a full test suite
 
-One important nuance: `doctor` is checking for broken JSKIT ownership and visibility, not trying to stop you from editing app-owned files. For example, a managed file that still exists but whose contents changed is normally fine. The problem is when JSKIT expects a managed file to exist and it is gone, or when the installed package state no longer resolves cleanly.
+One important nuance: `doctor` is checking for broken JSKIT ownership and visibility, not trying to stop you from editing app-owned files. For example, a managed file that still exists but whose contents changed is normally fine. An app-owned file explicitly installed by a package can also live under `packages/main/src/server/` without being mistaken for undeclared domain logic. The file remains part of managed state, so deleting it is still an error. Unrelated server files under `packages/main` continue to receive the normal feature-lane warning.
 
 There is one intentional exception for user-facing UI work.
 
@@ -799,6 +818,8 @@ That command does two things:
 - runs the targeted Playwright command you give it
 - writes a receipt describing the verified feature, auth mode, and current dirty UI file set
 
+The auth mode is receipt metadata, not an authentication implementation. `jskit app verify-ui` does not log a user in, inject a secret, or rewrite the Playwright context. A direct local run uses `loginAsExistingUser()` from `@jskit-ai/auth-web/test/playwright`; a managed runner supplies authenticated state through `JSKIT_PLAYWRIGHT_STORAGE_STATE`. The generated `playwright.config.mjs` consumes that state and honors `PLAYWRIGHT_BASE_URL` without starting a second server.
+
 `doctor` then compares the current changed UI files to that receipt. If you edit the UI again afterwards, the receipt is stale and `doctor` tells you to rerun `jskit app verify-ui`.
 
 For local pre-merge review, use `--against <base-ref>` so JSKIT compares against the branch delta instead of only the current dirty worktree. The common shape is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/ui-testing.md

@@ -11,80 +11,88 @@ Rules:
 
 - Any chunk that adds or changes user-facing UI must include a Playwright flow that exercises the changed behavior before the chunk is done.
 - Generator or package template UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
-- For generated UI, the browser checks should cover horizontal overflow, clipped text, invisible text, duplicate navigation, broken route placement, and tap targets under 48 px.
-- Apps with `shell-web` installed should start from the generated `tests/e2e/adaptive-shell.spec.ts` smoke and extend it for feature-specific assertions.
-- Record that Playwright run with `jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
-- `jskit doctor` expects `.jskit/verification/ui.json` to match the current dirty UI file set when UI files are changed.
-- For local pre-merge review, follow the recorded Playwright run with `jskit doctor --against <base-ref>` so `doctor` compares against the branch delta instead of only the local dirty worktree.
-- Advanced CI setups may also use `--against <base-ref>`, but JSKIT does not scaffold hosted browser/auth/database verification by default.
-- Do not rely on a live external auth provider for Playwright verification of normal app features.
-- For authenticated UI in the standard JSKIT auth stack, use the development-only dev auth bypass route instead.
-- The standard route is `POST /api/dev-auth/login-as`.
-- The request body must include either `{ userId }` or `{ email }`.
-- The route is available only when `AUTH_DEV_BYPASS_ENABLED=true` and `AUTH_DEV_BYPASS_SECRET` is set outside production.
-- This route must never be enabled in production.
-- Because the route is an unsafe POST, fetch `csrfToken` from `/api/session` first and send it back as the `csrf-token` header.
-- Make the bootstrap request from the same browser context that will run the assertions so the auth cookies land in the page session.
-- Use stable seeded users or fixtures for Playwright. Do not depend on whatever account happens to exist in a developer's browser or external auth provider.
-
-Recommended flow:
+- For generated UI, check horizontal overflow, clipped or invisible text, duplicate navigation, broken route placement, and tap targets under 48 px.
+- Apps with `shell-web` installed should start from `tests/e2e/adaptive-shell.spec.ts` and extend it with feature-specific assertions.
+- Generated `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`. Do not copy base-URL, web-server, or storage-state logic into app tests.
+- Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
+- A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.
+- A managed runner supplies an authenticated context through `JSKIT_PLAYWRIGHT_STORAGE_STATE`. Treat that file as a temporary secret: do not commit it, print it, or retain it after the run.
+- Do not install a browser when the environment provides a managed browser runner.
+
+## Direct local authentication
+
+Use the development-only dev auth bypass when Playwright is talking directly to an app running on localhost.
+
+The app must start with:
 
 ```bash
-npx jskit app verify-ui \
-  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
-  --feature "contacts filters" \
-  --auth-mode dev-auth-login-as
+AUTH_DEV_BYPASS_ENABLED=true
+AUTH_DEV_BYPASS_SECRET=replace-this-with-a-local-dev-secret
+```
+
+The test uses the published Node-side helper:
+
+```ts
+import { expect, test } from "@playwright/test";
+import { loginAsExistingUser } from "@jskit-ai/auth-web/test/playwright";
+
+test("authenticated feature", async ({ page }) => {
+  await loginAsExistingUser(page, { email: "ada@example.com" });
+  await page.goto("/w/acme/admin/contacts");
+  await expect(page.getByRole("heading", { name: "Contacts" })).toBeVisible();
+});
 ```
 
-Local pre-merge follow-up:
+`loginAsExistingUser()`:
+
+- uses the request client belonging to the same Playwright browser context
+- fetches the CSRF token from `GET /api/session`
+- sends the CSRF token and private `x-jskit-dev-auth-secret` header to `POST /api/dev-auth/login-as`
+- leaves the resulting HTTP-only cookies in that browser context
+- refuses to send the secret to a non-local URL
+
+The helper reads `AUTH_DEV_BYPASS_SECRET` from the Playwright Node process by default. Never pass that secret through `page.evaluate()`, browser globals, query parameters, or client-visible environment variables.
+
+The route only selects an existing user. Seed a stable user or fixture before the test. The bypass must never be enabled in production.
+
+## Managed-host authentication
+
+A managed preview must not expose `AUTH_DEV_BYPASS_SECRET` to project code or forward an ordinary browser request to the private login exchange. The host performs its trusted identity exchange outside the application browser context, writes a temporary Playwright storage-state file, and launches the test with:
 
 ```bash
-npx jskit doctor --against origin/main
+PLAYWRIGHT_BASE_URL=https://managed-preview.example.test \
+JSKIT_PLAYWRIGHT_STORAGE_STATE=/secure/temp/playwright-state.json \
+playwright test tests/e2e/contacts.spec.ts
 ```
 
-The Playwright command itself should follow this setup shape when login is needed:
+The generated config applies that state to Playwright contexts and omits its local `webServer`. Tests then navigate with relative paths and begin with the runner-provided identity already authenticated.
 
-```ts
-await page.goto("/");
-
-await page.evaluate(async ({ email }) => {
-  const sessionResponse = await fetch("/api/session", {
-    credentials: "include"
-  });
-  if (!sessionResponse.ok) {
-    throw new Error(`Session bootstrap failed: ${sessionResponse.status}`);
-  }
-
-  const sessionPayload = await sessionResponse.json();
-  const csrfToken = String(sessionPayload?.csrfToken || "");
-  if (!csrfToken) {
-    throw new Error("Missing csrfToken from /api/session.");
-  }
-
-  const loginResponse = await fetch("/api/dev-auth/login-as", {
-    method: "POST",
-    credentials: "include",
-    headers: {
-      "content-type": "application/json",
-      "csrf-token": csrfToken
-    },
-    body: JSON.stringify({ email })
-  });
-
-  if (!loginResponse.ok) {
-    throw new Error(`Dev login failed: ${loginResponse.status} ${await loginResponse.text()}`);
-  }
-}, { email: "ada@example.com" });
+Do not call `loginAsExistingUser()` against a managed preview. It is deliberately localhost-only. An ordinary request to `/api/dev-auth/login-as` without the private exchange header must return `403`.
+
+## Recording verification
+
+After the Playwright command succeeds, record it with:
+
+```bash
+npx jskit app verify-ui \
+  --command "npx playwright test tests/e2e/contacts.spec.ts -g filters" \
+  --feature "contacts filters" \
+  --auth-mode dev-auth-login-as
 ```
 
-After that bootstrap:
+Use `--auth-mode session-bootstrap` when a managed runner supplied authenticated storage state.
+
+`jskit app verify-ui` runs the command and records its command, auth-mode label, feature, and changed UI files in `.jskit/verification/ui.json`. The auth-mode option describes how the command was authenticated; it does not create a session or modify the Playwright context.
+
+For local pre-merge review, follow the recorded run with:
 
-- navigate to the protected page
-- exercise the new UI behavior
-- assert the actual outcome the chunk introduced
+```bash
+npx jskit doctor --against origin/main
+```
 
 Do not mark the chunk done if:
 
 - the feature changed user-facing UI but no Playwright flow ran
 - the Playwright flow skipped the changed behavior itself
-- authenticated UI work was left untested because no local auth bootstrap path was available and that gap was not called out
+- a managed environment was bypassed by installing another browser
+- an authenticated flow was left untested without clearly reporting the missing session-bootstrap seam

package/reference/autogen/tooling/create-app.md

@@ -116,6 +116,10 @@ Exports
 Exports
 - None
 
+### `templates/base-shell/playwright.config.mjs`
+Exports
+- None
+
 ### `templates/base-shell/server.js`
 Exports
 - `createServer()`
@@ -266,6 +270,10 @@ Exports
 Exports
 - None
 
+### `templates/minimal-shell/playwright.config.mjs`
+Exports
+- None
+
 ### `templates/minimal-shell/server.js`
 Exports
 - `createServer()`

package/reference/autogen/tooling/jskit-cli.md

@@ -572,7 +572,9 @@ Exports
 
 ### `src/server/commandHandlers/appCommands/updatePackages.js`
 Exports
+- `collectChangedInstalledPackageIds(lock = {}, latestVersions = new Map())`
 - `formatElapsedTime(elapsedMilliseconds = 0)`
+- `reapplyChangedInstalledPackages({ appRoot, createCliError, dryRun, latestVersions, loadLockFile, stderr, stdout })`
 - `runAppUpdatePackagesCommand(ctx = {}, { appRoot = "", options = {}, stdout, stderr })`
 - `runWithProgress(task, { activity, progressIntervalMs = PROGRESS_INTERVAL_MS, stdout, step } = {})`
 Local functions