@jskit-ai/agent-docs 0.1.292 → 0.1.294

package/skills/jskit/references/patterns/users/user-administration-server/PATTERN.md

@@ -38,9 +38,13 @@ variant also names `visibility: "workspace"`: its routes are a workspace's,
 so they resolve the caller's workspace and check its `crud.users.*`
 permissions. The `users` table is public, every user's, so the variant also
 narrows the repository to the workspace's members with `decorateRepository`
-(`src/server/workspaceMembersOnly.js`): a list reads only the active members
-from `workspaces.memberships`' `activeMemberIds`, and anyone else is a missing
-record, so a workspace admin never learns who else has an account. The narrowed
+(`src/server/workspaceMembersOnly.js`): a list reads only the active members,
+and anyone else is a missing record, so a workspace admin never learns who else
+has an account. Each page is one report over users.profiles' and
+`workspaces.memberships`' join sources: the users the list's filters match that
+hold an active membership, in the users list's order, a page at a time, so it
+never reads the workspace's memberships whole; a view reads the one membership
+with `findByWorkspaceIdAndUserId`. The narrowed
 repository answers only `query`, `get` and `pageLimits`: users.profiles' other
 methods (`findByEmail`, `countUsers`, the writes) read or write every user, so
 they never pass through it.

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

@@ -10,9 +10,9 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.22",
-    "@jskit-ai/resource-crud-core": "0.1.208",
-    "@jskit-ai/users-core": "0.2.23"
+    "@jskit-ai/crud-core": "0.2.24",
+    "@jskit-ai/resource-crud-core": "0.1.210",
+    "@jskit-ai/users-core": "0.2.25"
   },
   "jskit": {
     "kind": "runtime",

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

@@ -10,14 +10,14 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.2.22",
-    "@jskit-ai/resource-crud-core": "0.1.208",
-    "@jskit-ai/users-core": "0.2.23",
-    "@jskit-ai/workspaces-core": "0.2.23"
+    "@jskit-ai/crud-core": "0.2.24",
+    "@jskit-ai/resource-crud-core": "0.1.210",
+    "@jskit-ai/users-core": "0.2.25",
+    "@jskit-ai/workspaces-core": "0.2.25"
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.2.17",
-    "@jskit-ai/resource-runtime": "0.2.19"
+    "@jskit-ai/kernel": "0.2.18",
+    "@jskit-ai/resource-runtime": "0.2.21"
   },
   "jskit": {
     "kind": "runtime",

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

@@ -1,43 +1,95 @@
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { passedOn, resolveWorkspaceScopeValue } from "@jskit-ai/resource-runtime/server";
 
+// The page size json-rest-api reads for a list that names none.
+const DEFAULT_PAGE_SIZE = 20;
+
+// A page's cursor: the display name, email and id of its last user, the users list's order, as base64url JSON.
+function encodeCursor(row) {
+  return Buffer.from(JSON.stringify([row.displayName, row.email, String(row.id)])).toString("base64url");
+}
+
+function decodeCursor(cursor) {
+  try {
+    const [displayName, email, id] = JSON.parse(Buffer.from(String(cursor), "base64url").toString("utf8"));
+    if ([displayName, email, id].every((value) => typeof value === "string")) {
+      return { displayName, email, id };
+    }
+  } catch {
+    // Not a cursor this list answered: refused below.
+  }
+  throw new AppError(400, "This list's cursor is not one it answered.", { code: "users.list.cursorInvalid" });
+}
+
 /**
  * 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
+ * public, so its handle alone would list every user. A page is one report over the users the list's filters match
+ * that hold an active membership in the workspace, in the users list's order, so it reads a page of rows however many
+ * members the workspace has; the users repository then reads that page's users as the CRUD contract answers them. 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 & Pick<import("@jskit-ai/users-core/server/types").UsersProfiles, "joinSource">} repository
+ * @param {import("@jskit-ai/workspaces-core/server/types").WorkspacesMemberships} 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));
+  // Knex: report - one page of the users the list's filters match that are active members of the workspace, in the users list's order
+  async function memberPage(workspaceId, filters, { size, after }, options) {
+    const user = await repository.joinSource({ alias: "u", ...(filters === undefined ? {} : { filters }) }, options);
+    const member = await memberships.joinSource({ alias: "m", filters: { workspace: workspaceId, status: "active" } }, options);
+    const [shown, mail, key] = [user.column("displayName"), user.column("email"), user.column("id")];
+    const query = user.query
+      .whereExists(member.query.select(member.column("id")).whereColumn(member.column("userId"), key))
+      .select({ id: key, displayName: shown, email: mail })
+      .orderBy([shown, mail, key])
+      .limit(size + 1);
+    if (after !== undefined) {
+      const last = decodeCursor(after);
+      query.where((later) => later.where(shown, ">", last.displayName)
+        .orWhere((tie) => tie.where(shown, last.displayName).where(mail, ">", last.email))
+        .orWhere((tie) => tie.where(shown, last.displayName).where(mail, last.email).where(key, ">", last.id)));
+    }
+    const rows = await query;
+    return { ids: rows.slice(0, size).map((row) => String(row.id)), next: rows.length > size ? encodeCursor(rows[size - 1]) : null };
   }
 
   /**
-   * One page of the workspace's members the params select.
+   * One page of the workspace's members the params select: the report picks the page's users, the users repository
+   * reads them, and the page's cursor is the report's.
    * @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);
+    const workspaceId = resolveWorkspaceScopeValue(options.context);
+    const size = Number(params.page?.size ?? DEFAULT_PAGE_SIZE);
+    const after = params.page?.after;
+    // A context with no workspace has no members: the page is empty.
+    const page = workspaceId
+      ? await memberPage(workspaceId, params.filters, { size: Math.min(size, repository.pageLimits().request), after }, passedOn(options))
+      : { ids: [], next: null };
+    // An empty list matches no row. A size over the page limit throws here, as the users list's own read does.
+    const result = await repository.query({ ...params, filters: { id: page.ids }, page: { size } }, options);
+    const hasMore = page.next !== null;
+    if (options.format !== "jsonapi") {
+      return { records: result.records, page: { size, hasMore, next: page.next } };
+    }
+    // The users read's own links would name its id list; the page's cursor is the report's.
+    const { links: _links, ...document } = result;
+    return {
+      ...document,
+      meta: { ...document.meta, pagination: { pageSize: size, hasMore, ...(hasMore ? { cursor: { next: page.next } } : {}) } }
+    };
   }
 
   /**
-   * A member of the workspace, or a missing record for anyone else.
+   * A member of the workspace, or a missing record for anyone else. It reads the one membership.
    * @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))) {
+    const membership = await memberships.findByWorkspaceIdAndUserId(resolveWorkspaceScopeValue(options.context), id, passedOn(options));
+    if (membership?.status === "active") {
       return repository.get(id, params, options);
     }
     if (options.missing === "skip") {

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

@@ -74,6 +74,15 @@ 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.
 
+Provide the optional `workspaces.workspace-created-participant` capability the
+same way to write application records for every new workspace. The
+`workspace.workspaces.create` action and personal workspace provisioning invoke
+`fn({ workspace, owner }, txOptions)` after writing the workspace, its owner's
+membership and its settings, in the creation's uncommitted transaction (the
+caller's when it passes one). Pass `txOptions` on and propagate failures: a
+failure rolls the whole creation back. An existing personal workspace does not
+call it.
+
 Call `members.prepareInvite(workspace, actor, payload, txOptions)` inside
 `repositories.workspaceInvites.withTransaction(options, async (txOptions) => …)`
 or another resource handle's `withTransaction`. It returns

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

@@ -67,13 +67,13 @@ expects the relationship id or an unselected field never gets it.
 ### Every row
 
 - A handle's `query()` answers one page and refuses a missing or oversized
-  `page.size`, where json-rest-api would cut the list silently. A read its
-  callers treat as complete uses `queryAll()`, or the missing rows vanish from
-  every picker and delivery built on it
+  `page.size`, where json-rest-api would cut the list silently. A delivery
+  reaching every row uses `queryAll()`; a picker reads a page searched with
+  `q` and its selected values by `id`
   ([Reads](data-access.md#reads-shaped-for-the-screen)).
 - A grouped `aggregate()` answers every group or throws
   `RESOURCE_GROUP_LIMIT`; past `pageLimits().request` groups, page it with
-  `page: { size, number }`
+  `page: { size, number }` (answers `{ rows, page }`)
   ([The handle's calls](data-access.md#the-handle-s-calls)).
 - A lookup by a unique key matches at most one row: `get(id)`, or a `query()`
   of page size 1.

package/skills/jskit/references/typed-features.md

@@ -76,6 +76,31 @@ setup: ({ resources }) => ({ invoices: { list: (options) => resources.invoices.q
 actions: ({ invoices }) => [{ id: "invoices.list", execute: () => invoices.list() }]
 ```
 
+### Package manifest
+
+**A package's manifest, `jskit.capabilities` in its `package.json`, lists
+exactly what its features provide, and every capability they require beyond
+the kernel's own (`runtime.actions`, `runtime.events`, `runtime.http`,
+`runtime.bootstrap`) and those the package provides itself.** Optional
+capabilities are not required. A requirement no feature has stays only when
+the package needs it at install time, such as the database its migrations
+need.
+
+Why: start-up resolves every package's requirements from the manifests, and
+refuses a manifest that disagrees with the package's features. Plain
+`jskit check` loads each application package's features (the server providers
+`jskit.runtime.server.providers` declares) and reports the drift before that
+(`manifest/capabilities`), each capability to add or remove; it lists the
+requirements no feature has for review.
+
+```jsonc
+// good: BooksFeature provides app.books and requires crud.contracts and runtime.actions
+"capabilities": { "provides": ["app.books"], "requires": ["crud.contracts"] }
+
+// bad: app.books missing from provides, crud.contracts from requires
+"capabilities": { "provides": ["app.book"], "requires": [] }
+```
+
 ### Capability types
 
 **Each provided token has one `@typedef` in its package's `src/server/types.js`,
@@ -622,9 +647,9 @@ Why: a value with two defaults has two meanings, and a mode flag hides a
 second method inside the first.
 
 ```js
-// good
-async function list(filters, options = {}) {
-  return invoices.queryAll({ filters }, options);
+// good: one page, as a list shows it
+async function list(filters, page, options = {}) {
+  return invoices.query({ filters, page }, options);
 }
 
 // bad
@@ -691,6 +716,11 @@ way (is this user an operator) is a member of its owner's capability.**
   meaning of 0 and false before replacing a copy.
 - A helper two packages of an application use lives in its shared package,
   never inside one of them.
+- A component's closure over its own state is not a helper: a function of at
+  most two statements in `<script setup>` whose every outside name is a
+  binding `<script setup>` declares (not an import or a global). Two pages
+  that reload their own resources the same way keep their own `reload()`;
+  sharing it would take a module that receives each page's state.
 
 Why: the kernel's helpers fix one meaning of empty, and a copy brings its own.
 
@@ -741,6 +771,13 @@ handle's `queryAll(params, options)`. A `query()` names its page size, and
 answers one page.** [Reads shaped for the screen](data-access.md#reads-shaped-for-the-screen)
 gives the rules and examples.
 
+### Narrow in the query
+
+**A read asks for exactly the rows the code uses: its filter, sort, limit,
+existence check and count go in the read, never in code over the rows it
+answered.** [Narrow in the query](data-access.md#narrow-in-the-query)
+gives the rules and examples.
+
 ### Lists read related rows in batches
 
 **A read that builds a list fetches its related rows in batches, an id-list
@@ -1170,8 +1207,9 @@ Why: a comment that narrates history is wrong the day after it is written.
 
 `npm run lint` runs ESLint with `@jskit-ai/config-eslint`, and `npm run
 verify` runs `jskit check` (the package graph, navigation, [data
-access](data-access.md#exceptions) and [test
-runs](#test-run-rules)), lint, the tests and the build. The foundations'
+access](data-access.md#exceptions), [test
+runs](#test-run-rules) and [package manifests](#package-manifest)), lint, the
+tests and the build. The foundations'
 `eslint.config.mjs` already holds a new
 application's code to every check:
 
@@ -1241,6 +1279,7 @@ Every finding ends with a link to the section of this page that explains it.
 | `jskit/app-error-code` | an `AppError`, `DomainError`, `ConflictError` or `NotFoundError` (or a subclass the module declares) without its own code, and one code naming two sentences in a module | [Refusals carry their own code](#refusals-carry-their-own-code) |
 | `jskit/no-patched-error` | `Object.assign(new Error(…), { statusCode })`, or an error builder's result given its status afterwards | [One construction per error](#one-construction-per-error) |
 | `jskit/no-test-only-export` | an export whose name says only tests use it (`…ForTests`, `__reset…`; `__testables` aside) | [No test-only exports](#no-test-only-exports) |
+| `jskit/narrow-in-query` | `.filter()`, `.find()`, `.some()`, `.every()`, `.slice()`, a lone `.length` or a loop that skips with `continue`, over the rows a read in the same function answered and uses no other way | [Narrow in the query](#narrow-in-the-query) |
 | `jskit/one-property-per-line` | two properties on one line in a returned `Object.freeze({ … })` or a `requires` / `optional` / `provides` map (`eslint --fix` splits them) | [Formatter](#formatter) |
 | `jskit/jsdoc-description-inside` | a `//` description directly above a `/** */` block | [Comments](#comments) |
 | `jskit/allow-comment-form` | a `readable-check: allow` reason without a prefix from the table below, or one that cites tests or the state of a project | [Exceptions](#exceptions) |
@@ -1292,6 +1331,7 @@ if (typeof buildSerializer !== "function") {
 | `filled by <repository>; convert with its supplier` | keeps a setter that another repository's code calls |
 | `cross-repository slot <token>` | keeps a probe for a token another repository supplies |
 | `shared resource:` | keeps client module state that every instance on the page shares on purpose ([client features](client-features.md#module-state)) |
+| `every row: <why>` | code needs every row a read answers and narrows them for its own use, such as a read the data itself keeps small (a conversation's few summaries) whose oldest ones it deletes (`jskit/narrow-in-query`) |
 | `infrastructure: <what the module is>` | excuses a whole file whose job is data access itself from `jskit/no-direct-knex` or `jskit/no-transaction-reader`, one line per rule before its first line of code ([data access](data-access.md#exceptions)) |
 
 One kind of probe gets one prefix and one wording everywhere, and a bare