@jskit-ai/agent-docs 0.1.283 → 0.1.285

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -10,8 +10,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.14",
-    "@jskit-ai/resource-crud-core": "0.1.204"
+    "@jskit-ai/crud-core": "0.2.16",
+    "@jskit-ai/resource-crud-core": "0.1.206",
+    "@jskit-ai/users-core": "0.2.17"
   },
   "jskit": {
     "kind": "runtime",
@@ -20,10 +21,10 @@
         "app.users"
       ],
       "requires": [
+        "crud.contracts",
         "runtime.http",
-        "runtime.json-rest-api",
         "runtime.actions",
-        "runtime.database"
+        "users.profiles"
       ]
     },
     "runtime": {

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/server/UsersFeature.js

@@ -1,12 +1,14 @@
-import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
-import { resource } from "../shared/userResource.js";
+import { defineCrudFeature } from "@jskit-ai/crud-core/server/defineCrudFeature";
+import { userCrud } from "../shared/userCrud.js";
 
-const UsersFeature = defineCrudJsonApiFeature({
-  resource,
+// users-core owns the users table; this feature serves the administration
+// CRUD contract through its owner's repository.
+const UsersFeature = defineCrudFeature({
+  crud: userCrud,
+  ownerRepository: "users.profiles",
   id: "app.users",
   capability: "app.users",
   surface: "home",
-  ownershipFilter: "public",
   relativePath: "/users"
 });
 

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/index.js

@@ -1 +1 @@
-export { resource } from "./userResource.js";
+export { userCrud } from "./userCrud.js";

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/userCrud.js

@@ -0,0 +1,21 @@
+import { defineCrudContract } from "@jskit-ai/resource-crud-core/shared/crudContract";
+import { userProfileTableResource } from "@jskit-ai/users-core/shared/resources/userProfileResource";
+
+// The users list and view. The users table has one table resource, users-core's
+// userProfileTableResource; this contract chooses the operations and the fields they
+// return, and the list searches with the resource's q (display name, email and
+// username). It shows only the fields it names, so the sign-in identity and the
+// avatar's storage stay out of administration.
+const userCrud = defineCrudContract(userProfileTableResource, {
+  namespace: "users",
+  operations: ["list", "view"],
+  fields: {
+    displayName: { output: "optional" },
+    email: { output: "optional" },
+    username: { output: "optional" },
+    createdAt: { output: "required" },
+    updatedAt: { output: "required" }
+  }
+});
+
+export { userCrud };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/package.json

@@ -10,9 +10,14 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.14",
-    "@jskit-ai/resource-crud-core": "0.1.204",
-    "@jskit-ai/workspaces-core": "0.2.15"
+    "@jskit-ai/crud-core": "0.2.16",
+    "@jskit-ai/resource-crud-core": "0.1.206",
+    "@jskit-ai/users-core": "0.2.17",
+    "@jskit-ai/workspaces-core": "0.2.17"
+  },
+  "peerDependencies": {
+    "@jskit-ai/kernel": "0.2.15",
+    "@jskit-ai/resource-runtime": "0.2.13"
   },
   "jskit": {
     "kind": "runtime",
@@ -21,10 +26,11 @@
         "app.users-workspace"
       ],
       "requires": [
+        "crud.contracts",
         "runtime.http",
-        "runtime.json-rest-api",
         "runtime.actions",
-        "runtime.database"
+        "users.profiles",
+        "workspaces.memberships"
       ]
     },
     "runtime": {

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/server/UsersWorkspaceFeature.js

@@ -1,13 +1,22 @@
-import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
+import { defineCrudFeature } from "@jskit-ai/crud-core/server/defineCrudFeature";
 import { WORKSPACE_CRUD_SCOPE } from "@jskit-ai/workspaces-core/server/support/workspaceCrud";
-import { resource } from "../shared/userResource.js";
+import { userCrud } from "../shared/userCrud.js";
+import { workspaceMembersOnly } from "./workspaceMembersOnly.js";
 
-const UsersWorkspaceFeature = defineCrudJsonApiFeature({
-  resource,
+// users-core owns the users table; this feature serves the administration
+// CRUD contract on a workspace's admin surface through its owner's
+// repository. The routes are a workspace's, so they resolve the caller's
+// workspace and check its crud.users.* permissions, and the repository is
+// narrowed to that workspace's members: the users table is every user's.
+const UsersWorkspaceFeature = defineCrudFeature({
+  crud: userCrud,
+  ownerRepository: "users.profiles",
+  requires: { memberships: "workspaces.memberships" },
+  decorateRepository: ({ repository, memberships }) => workspaceMembersOnly(repository, memberships),
+  visibility: "workspace",
   id: "app.users-workspace",
   capability: "app.users-workspace",
   surface: "admin",
-  ownershipFilter: "workspace",
   relativePath: "/users",
   scope: WORKSPACE_CRUD_SCOPE
 });

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/server/workspaceMembersOnly.js

@@ -0,0 +1,52 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
+import { passedOn, resolveWorkspaceScopeValue } from "@jskit-ai/resource-runtime/server";
+
+/**
+ * users-core's users repository narrowed to the caller's workspace: a list reads only the workspace's active members,
+ * and anyone else is a missing record, so a workspace admin never learns who else has an account. The users table is
+ * public, so its handle alone would list every user; the narrowing reads the workspace's memberships first. It answers
+ * only the reads it narrows (query and get, with pageLimits): the rest of users.profiles, such as findByEmail or
+ * countUsers, never passes through this feature's repository, so nothing reaches users past the narrowing through it.
+ * @param {import("@jskit-ai/crud-core/server/types").CrudRepository} repository
+ * @param {import("@jskit-ai/workspaces-core/server/types").WorkspaceMembershipsRepository} memberships
+ */
+function workspaceMembersOnly(repository, memberships) {
+  // The caller's workspace's active members; none when the context names no workspace. The memberships get only the
+  // context and transaction: the list's own settings (its format, missing) are for the users read.
+  function memberIds(options) {
+    return memberships.activeMemberIds(resolveWorkspaceScopeValue(options.context), passedOn(options));
+  }
+
+  /**
+   * One page of the workspace's members the params select.
+   * @param {Record<string, any>} params
+   * @param {{ context?: object }} options
+   */
+  async function query(params, options) {
+    const members = await memberIds(options);
+    const requested = params.filters?.id;
+    // An empty list matches no row: a workspace with no members lists nobody.
+    const id = requested === undefined ? members : [requested].flat().map(String).filter((memberId) => members.includes(memberId));
+    return repository.query({ ...params, filters: { ...params.filters, id } }, options);
+  }
+
+  /**
+   * A member of the workspace, or a missing record for anyone else.
+   * @param {unknown} id
+   * @param {Record<string, any>} params
+   * @param {{ context?: object, missing?: "skip" }} options
+   */
+  async function get(id, params, options) {
+    if ((await memberIds(options)).includes(String(id))) {
+      return repository.get(id, params, options);
+    }
+    if (options.missing === "skip") {
+      return null;
+    }
+    throw new AppError(404, "Document not found.", { code: "crud.document.notFound" });
+  }
+
+  return Object.freeze({ query, get, pageLimits: repository.pageLimits });
+}
+
+export { workspaceMembersOnly };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/index.js

@@ -1 +1 @@
-export { resource } from "./userResource.js";
+export { userCrud } from "./userCrud.js";

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users-workspace/src/shared/userCrud.js

@@ -0,0 +1,21 @@
+import { defineCrudContract } from "@jskit-ai/resource-crud-core/shared/crudContract";
+import { userProfileTableResource } from "@jskit-ai/users-core/shared/resources/userProfileResource";
+
+// The users list and view. The users table has one table resource, users-core's
+// userProfileTableResource; this contract chooses the operations and the fields they
+// return, and the list searches with the resource's q (display name, email and
+// username). It shows only the fields it names, so the sign-in identity and the
+// avatar's storage stay out of administration.
+const userCrud = defineCrudContract(userProfileTableResource, {
+  namespace: "users",
+  operations: ["list", "view"],
+  fields: {
+    displayName: { output: "optional" },
+    email: { output: "optional" },
+    username: { output: "optional" },
+    createdAt: { output: "required" },
+    updatedAt: { output: "required" }
+  }
+});
+
+export { userCrud };

package/skills/jskit/references/patterns/workspaces/workspace-server/PATTERN.md

@@ -66,20 +66,20 @@ catalogue entries. Updating labels requires no database migration.
 Provide one function as the optional `workspaces.invite-acceptance-participant`
 capability, from a small application feature that requires only what its writes
 need (it cannot require `workspaces.core`, which receives it). The built-in
-`workspace.invite.redeem` action invokes `fn({ invite, user }, { trx, context })`
+`workspace.invite.redeem` action invokes `fn({ invite, user }, txOptions)`
 after validating the recipient, state and expiry and activating membership in the
-uncommitted transaction. Forward `trx` to every application owner and propagate
-failures. JSKIT marks accepted and commits after the function succeeds. Keep
+uncommitted transaction. Pass `txOptions` to every application owner's calls and
+propagate failures. JSKIT marks accepted and commits after the function succeeds. Keep
 external effects out of it. Without the capability, acceptance activates the
 membership only. Allow ordinary invitations; reject stale, revoked, conflicting
 or unexpectedly missing application associations.
 
-Use `members.prepareInvite(workspace, actor,
-payload, { trx, context })` in `repositories.workspaceInvites.withTransaction`
-or the same JSON REST API's managed `transaction`. It returns
+Call `members.prepareInvite(workspace, actor, payload, txOptions)` inside
+`repositories.workspaceInvites.withTransaction(options, async (txOptions) => …)`
+or another resource handle's `withTransaction`. It returns
 `{ createdInviteId, inviteTokenPreview }` without delivery. Lock the workspace
-with `repositories.workspaceInvites.lockWorkspaceForInvitations(workspace.id,
-{ trx })` before application draft/receipt rows, and save the exact invitation
+with `lock(workspace.id, txOptions)` of the `workspaces` capability before
+application draft/receipt rows, and save the exact invitation
 association and retry receipt before commit. Failure restores the previous
 pending invitation. Keep access drafts separate: preparation creates a real token.
 
@@ -92,7 +92,7 @@ failure. A provider may accept a message before failing; the application owns
 receipts and retries. Keep tokens/URLs out of logs and use controlled mailers in tests.
 
 `createInvite`, acceptance and refusal own their managed transactions and
-reject a borrowed `options.trx`. Use preparation followed by delivery after commit for
+refuse a call made inside one (`withTransaction({ ...options, outermost: true }, work)`). Use preparation followed by delivery after commit for
 transactional creation; put related acceptance writes in the participant. Revocation may join
 a managed transaction. Raw Knex/savepoint transactions cannot own resource
 writes. Invitation mutations lock workspace then invitation rows, revalidate

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/PATTERN.md

@@ -54,6 +54,22 @@ the **Your workspaces** page at `src/pages/home/workspaces/index.vue`, member
 and settings routes, not-found state, app-owned invitation widgets, and the
 components that an application's client provider registers.
 
+`example/src/surfaces/<surface>/` and `example/src/pages/admin/` are each
+surface's own pages; the app puts them under the surface's `pagesRoot`. With
+`pagesRoot: "w/[workspaceSlug]"` for `app` and `"w/[workspaceSlug]/admin"` for
+`admin`:
+
+| Example file | App file |
+| --- | --- |
+| `src/surfaces/app/root.vue` | `src/pages/w/[workspaceSlug].vue` |
+| `src/surfaces/app/index.vue` | `src/pages/w/[workspaceSlug]/index.vue` |
+| `src/surfaces/admin/root.vue` | `src/pages/w/[workspaceSlug]/admin.vue` |
+| `src/surfaces/admin/index.vue` | `src/pages/w/[workspaceSlug]/admin/index.vue` |
+| `src/pages/admin/...` | `src/pages/w/[workspaceSlug]/admin/...` |
+
+The surface definitions and access policies they need are in the human
+guide's **Workspace tenancy → Surfaces and where `/` lands**.
+
 ## Variation points
 
 Change surfaces, routes, section owners, labels, icons, placement order,

package/skills/jskit/references/patterns/workspaces/workspace-surfaces/example/src/pages/home/workspaces/index.vue

@@ -4,4 +4,6 @@
 
 <script setup>
 import WorkspacesClientElement from "@jskit-ai/workspaces-web/client/components/WorkspacesClientElement";
+
+definePage({ meta: { jskit: { parent: "/" } } });
 </script>

package/skills/jskit/references/sanity-checks.md

@@ -3,10 +3,10 @@
 # Sanity checks
 
 Before calling a list, a save, a test, a refactor, a screen or a deployment
-done, measure what it actually costs and does, judge whether that is sane, and
-fix the cause when it is not. This page is the JSKIT part of that: the
-pitfalls JSKIT's own packages cause, then which JSKIT call, helper or setting
-applies each check, with one line on what the check catches and why.
+done, measure what it costs and does, judge whether that is sane, and fix the
+cause when it is not. This page holds JSKIT's part: the pitfalls JSKIT's own
+packages cause, then the JSKIT call, helper or setting that applies each
+check, with one line on what it catches and why.
 
 ## JSKIT's own pitfalls
 
@@ -66,36 +66,35 @@ expects the relationship id or an unselected field never gets it.
 
 ### Every row
 
-- An unpaged JSON:API query returns the first 20 rows, and a page above the
-  resource's `queryMaxLimit` (100 unless it sets one) is cut to that size,
-  both without an error; CRUD `queryDocuments()` refuses such a `limit`. A
-  read its callers treat as complete uses `queryAllJsonRestCollectionRows()`
-  or the repository's `queryEveryDocument()`, because the missing rows
-  otherwise vanish from every picker and delivery built on it
-  ([Every row](typed-features.md#every-row)).
-- A lookup by a unique key matches at most one row, so it may read `rows[0]`
-  of a plain query.
+- A handle's `query()` answers one page and refuses a missing or oversized
+  `page.size`, because json-rest-api would otherwise cut the list without an
+  error. A read its callers treat as complete uses `queryAll()`, because the
+  missing rows otherwise vanish from every picker and delivery built on it
+  ([Reads](data-access.md#reads-shaped-for-the-screen)).
+- A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
+  of page size 1.
 
 ### Query counts and batches
 
-- Count a path's queries with `countQueries()` from
-  `@jskit-ai/database-runtime/server/testDatabases` at a few rows and at a
+- Count a path's queries with `expectFlatQueries()` from
+  `@jskit-ai/resource-runtime/test`, or `countQueries()` from
+  `@jskit-ai/database-runtime/server/testDatabases`, at a few rows and at a
   realistic number; the count should follow tables and pages, not rows
-  ([Query counts at realistic
-  sizes](typed-features.md#query-counts-at-realistic-sizes)).
+  ([Tests](data-access.md#tests)).
 - A JSON:API read adds a few lookup and visibility queries per page and per
-  relationship field. That follows pages, so it is expected.
-- `getDocumentById()`, `queryDocuments()` or a service `get` inside a loop is
-  the usual per-row read; batch it with an id-list `searchSchema` filter or
-  `include`, grouped with `Map.groupBy()` ([Lists read related rows in
-  batches](typed-features.md#lists-read-related-rows-in-batches)).
+  relationship field, and json-rest-api reads each relationship's related ids
+  in one statement however many rows the page has. Both follow pages, not
+  rows, so `expectFlatQueries` passes them.
+- A handle's `get()` or `query()`, or a service `get`, inside a loop is the
+  usual per-row read; batch it with an id-list filter through `queryAll()` or
+  `include`, grouped with `Map.groupBy()`
+  ([Reads](data-access.md#reads-shaped-for-the-screen)).
 - A `rowPolicy` adds one correlated predicate to the query it is given, so
   its cost follows the rows read, not the subject's history. It runs on every
-  single-record read, including a write's default `returning: "full"` read
-  back, so a write that discards its result passes `returning: "minimal"` and
-  a batch of creates uses `createDocuments()`, in the owner's transaction
-  ([Bounded access
-  checks](typed-features.md#bounded-access-checks)).
+  single-record read, including a write's default `returning: "record"` read
+  back, so a write that discards its result passes `returning: "id"` or
+  `"none"`, and a batch uses the many-row writes (`createMany()`,
+  `patchMany()`) ([Layer 1](data-access.md#layer-1-the-table-resource)).
 
 ### Tests
 
@@ -113,7 +112,7 @@ expects the relationship id or an unselected field never gets it.
   duration, so slow preparation shows ([Test databases are prepared
   once](typed-features.md#test-databases-are-prepared-once),
   [integration test
-  databases](/guide/app-setup/database-layer#integration-test-databases)).
+  databases](database-layer.md#integration-test-databases)).
 
 ### Inputs and access