@jskit-ai/agent-docs 0.1.49 → 0.1.51

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -557,7 +557,7 @@ The default error policy is intent-based. Runtime code reports what kind of erro
 When app code catches a dynamic import failure itself, report it through the shell async module recovery runtime so it uses the same reload banner as router chunk failures:
 
 ```js
-import { useShellAsyncModuleRecoveryRuntime } from "@jskit-ai/shell-web/client";
+import { useShellAsyncModuleRecoveryRuntime } from "@jskit-ai/shell-web/client/asyncModuleRecovery";
 
 const asyncModuleRecovery = useShellAsyncModuleRecoveryRuntime();
 
@@ -572,6 +572,34 @@ try {
 
 `useShellAsyncModuleRecoveryRuntime()` returns `null` when the shell runtime is not available in the current Vue context. That lets app-owned components use optional chaining instead of duplicating shell-web's internal injection token.
 
+Use the narrow `@jskit-ai/shell-web/client/asyncModuleRecovery` subpath for this runtime, especially from modules that are imported by Node-mode Vitest suites. The aggregate `@jskit-ai/shell-web/client` barrel also exports the composable for normal Vite app code, but that barrel includes `.vue` component exports and can require Vue SFC handling in tests.
+
+Request connectivity failures use a separate shell recovery path. Generated apps already configure TanStack Query to retry transient failures with capped backoff. `shell-web` then observes the app's `jskit.client.query-client` and, when an active query finishes in a transport failure such as `Network request failed.` or `Failed to fetch`, reports an `app-recoverable` banner with a `Retry` action that refetches that exact query. Normal HTTP validation and application errors stay local to the screen.
+
+Imperative app code only needs the public runtime when it catches a request failure outside the standard query/resource composables:
+
+```js
+import { useShellRequestRecoveryRuntime } from "@jskit-ai/shell-web/client/requestRecovery";
+
+const requestRecovery = useShellRequestRecoveryRuntime();
+
+async function loadProjectAccess() {
+  try {
+    return await fetch("/api/project-access");
+  } catch (error) {
+    requestRecovery?.report(error, {
+      label: "Project access",
+      retry: loadProjectAccess
+    });
+    throw error;
+  }
+}
+```
+
+`useShellRequestRecoveryRuntime()` returns `null` when the shell runtime is not available in the current Vue context. Use the narrow `@jskit-ai/shell-web/client/requestRecovery` subpath for the same reason as async module recovery: it avoids pulling `.vue` component exports into Node-mode test suites.
+
+For query-backed screens, the default is automatic. Set `meta: { jskit: { requestRecovery: false } }` only when a query deliberately owns its entire connectivity recovery UI. Set `meta: { jskit: { requestRecoveryLabel: "Project access" } }` when the default `Request` label is too generic.
+
 ### The home page talks to the backend
 
 `src/pages/home/index.vue` uses Vue Query to fetch `/api/health` and display the result in the UI.

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

@@ -358,7 +358,7 @@ void bootstrapClientShellApp({
 });
 ```
 
-The flow is simple once you read it in order: config in, runtime in memory, router built from that runtime, app-owned Vue plugins created once, app bootstrapped. Pinia, Vue Query, the router, and Vuetify are owned by the base app bootstrap so runtime packages share the same instances instead of carrying independent copies.
+The flow is simple once you read it in order: config in, runtime in memory, router built from that runtime, app-owned Vue plugins created once, app bootstrapped. Pinia, Vue Query, the router, and Vuetify are owned by the base app bootstrap so runtime packages share the same instances instead of carrying independent copies. Passing the same `queryClient` into `bootstrapClientShellApp(...)` also gives `shell-web` the QueryClient it observes for automatic request recovery when transport failures exhaust their normal retries.
 
 <DocsInDepth title="In depth" preview-height="15rem">
 

package/package.json

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

package/patterns/INDEX.md

@@ -18,7 +18,7 @@ How to use it:
   - `page-scaffolding.md`
 - child crud, nested crud, embedded list, subroute, separate page, parent/child layout
   - `child-cruds.md`
-- crud scaffold, crud server, crud ui, table creation, migrations, `crud-server-generator`, `crud-ui-generator`
+- crud scaffold, crud server, crud ui, table creation, migrations, direct knex, weird-custom persistence, `crud-server-generator`, `crud-ui-generator`
   - `crud-scaffolding.md`
 - CRUD links, record placeholders, `paths.page()`, `resolveViewUrl`, `resolveEditUrl`, `resolveParams`
   - `crud-links.md`

package/patterns/client-requests.md

@@ -68,6 +68,9 @@ Error presentation rules:
 
 - Resource load failures should stay local to the screen with the runtime's `loadError` state and a retry action.
 - Do not force global banners for ordinary list/view/add-edit load failures; the shell error policy treats `resource-load` as `silent` by default.
+- Transport/connectivity failures are different from ordinary resource-load errors. `shell-web` observes the app QueryClient and reports active query failures such as `Network request failed.` or `Failed to fetch` through request recovery with a `Retry` action.
+- For imperative app-caught request failures outside the standard query/resource composables, use `useShellRequestRecoveryRuntime()` from `@jskit-ai/shell-web/client/requestRecovery` and pass a retry callback.
+- Use query meta `jskit.requestRecovery = false` only when a query owns its full connectivity recovery UI, and `jskit.requestRecoveryLabel` when the recovery banner needs a better label.
 - Use `useUiFeedback()` or `useCommand()` for user-triggered action feedback. Those flows report `action-feedback`, and the app-owned shell error policy decides the channel.
 - Use explicit shell error intents only for exceptional app-level cases: `app-recoverable` for recoverable shell/runtime failures and `blocking` for failures that require user attention.
 

package/patterns/crud-scaffolding.md

@@ -40,6 +40,18 @@ Meaning of `--internal`:
 - it only suppresses public HTTP CRUD route registration
 - it is not a substitute for ownership columns or action/route permissions
 
+When a weird-custom persistence lane is proposed:
+
+- Treat hand-written repositories for persisted app-owned entity tables as an exception path, not a normal choice.
+- That includes things like:
+  - direct knex instead of generated CRUD ownership
+  - a custom repository/service/provider stack for a normal persisted entity table
+  - inherited-ownership or mixed-visibility workarounds that dodge the standard CRUD ownership model
+- Before taking that path, stop and ask the developer for explicit approval.
+- Record the exact approval and the approved exception in `.jskit/WORKBOARD.md` before coding.
+- If that exception changes the durable architecture rather than only the current chunk, record it in `.jskit/APP_BLUEPRINT.md` too.
+- Without that explicit approval record, do not take the weird-custom persistence path.
+
 Avoid:
 
 - writing a hand migration for a CRUD table that JSKIT CRUD scaffolding is supposed to own

package/reference/autogen/packages/shell-web.md

@@ -207,6 +207,10 @@ Exports
 - `useShellErrorPresentationStore`
 - `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
 - `useShellAsyncModuleRecoveryRuntime`
+- `SHELL_REQUEST_RECOVERY_RUNTIME_KEY`
+- `isRecoverableRequestError`
+- `requestRecoveryMessage`
+- `useShellRequestRecoveryRuntime`
 - `BOOTSTRAP_PAYLOAD_HANDLER_TAG`
 - `registerBootstrapPayloadHandler`
 - `resolveBootstrapPayloadHandlers`
@@ -342,6 +346,40 @@ Local functions
 - `installRouterErrorBridge(app, errorRuntime, logger)`
 - `createShellAsyncModuleRecoveryRuntime({ app, logger = null } = {})`
 
+### `src/client/requestRecovery/index.js`
+Exports
+- `SHELL_REQUEST_RECOVERY_RUNTIME_KEY`
+- `useShellRequestRecoveryRuntime`
+- `isRecoverableRequestError`
+- `requestRecoveryMessage`
+
+### `src/client/requestRecovery/inject.js`
+Exports
+- `SHELL_REQUEST_RECOVERY_RUNTIME_KEY`
+- `isShellRequestRecoveryRuntime(value)`
+- `useShellRequestRecoveryRuntime()`
+
+### `src/client/requestRecovery/runtime.js`
+Exports
+- `createShellRequestRecoveryRuntime({ app, logger = null } = {})`
+- `isRecoverableRequestError(error = null)`
+- `requestRecoveryMessage(error = null, { label = "Request", message = "" } = {})`
+Local functions
+- `normalizeText(value, fallback = "")`
+- `errorMessage(error = null)`
+- `errorCode(error = null)`
+- `errorName(error = null)`
+- `normalizeRequestErrorStatus(error = null)`
+- `isCanceledRequestError(error = null)`
+- `resolveQueryMeta(query = null)`
+- `isRequestRecoveryDisabled(query = null)`
+- `resolveQueryRecoveryLabel(query = null)`
+- `isActiveQuery(query = null)`
+- `recoverableQueryError(query = null)`
+- `createQueryRetry(queryClient, query = null)`
+- `resolveQueryHash(query = null)`
+- `installRecoverableQueryObserver({ app, runtime, logger } = {})`
+
 ### `src/client/runtime/bootstrapRuntime.js`
 Exports
 - `createShellBootstrapRuntime({ app, logger = null, fetchImplementation = globalThis.fetch, bootstrapPath = DEFAULT_BOOTSTRAP_PATH } = {})`