@jini-ai/cms 0.3.10 → 0.4.0

package/dist/navigation/agent-tools.d.ts

@@ -1,83 +1,4 @@
-/**
- * @file The Navigation (Menus) agent-tool catalog — this domain's instance of the
- * per-domain `agent-tools.ts` convention `forms/agent-tools.ts` and `identity/agent-tools.ts`
- * already use.
- *
- * Purpose:
- * A static, in-process catalog describing every agent-callable tool this domain exposes and the
- * permission each carries. Every entry maps 1:1 onto a real exported function of
- * `navigation/menu-service.ts` (plus two pure reads over `MenuRepoPort`) — this catalog never names
- * an operation the domain cannot perform.
- *
- * Precedent already in this library: `navigation/contracts.ts` declares `NAVIGATION_AI_TOOLS` — a
- * design-note list of an intended future AI tool surface (`navigation.search`/`.get`/`.where_used`/
- * `.update`/`.assign`) for a DIFFERENT, not-yet-built delivery mechanism (a "change-set review
- * layer" HITL gateway; the list itself is unused anywhere in this build today). Two of its five
- * names do not correspond to any real, callable capability in this build: `navigation.search` has
- * no implementation beyond `MenuRepoPort.list` (folded into `menus_list_menus` below — there is no
- * separate text-search capability, matching how `identity_user_list`/`identity_role_list` are
- * likewise this library's "search" for their own domains), and `navigation.where_used` has no
- * implementation anywhere (`NavWhereUsedResult` is declared in `contracts.ts` but no function in
- * `navigation/` computes it — `entry_refs`-backed where-used, unlike `widgets`/`media`, was never
- * built for menus). Wrapping either literally would invent backend capability this catalog's own
- * discipline forbids; `menus_list_menus` + `menus_get_menu` are this build's honest equivalents of
- * "search"/"get".
- *
- * Deliberate absence (the point of a catalog, not an oversight):
- * - There is NO `menus_delete_menu` (nor a separate trash-only tool). `deleteMenu` is ONE function
- *   that performs BOTH steps of the deletion ladder, keyed off the menu's CURRENT status:
- *   a first call trashes (safe, unconditional), but a second call against an already-trashed menu
- *   PURGES it — a hard, irreversible delete, blocked only by a still-bound-location guard that
- *   itself can be bypassed with `force` (gated behind the separate `admin.menus.delete.force`
- *   permission). Unlike `widgets`/`media` (which expose trash and purge as two SEPARATE domain
- *   functions, letting a catalog safely wire trash alone), navigation has no decomposed trash-only
- *   entrypoint to call — the very same tool call, made twice, silently escalates from a reversible
- *   soft-delete into a permanent one. That is exactly the shape of risk `identity/agent-tools.ts`
- *   excludes `resetUserPassword` for: a single lever whose second pull does something categorically
- *   more dangerous than its first, reachable by an agent re-invoking a tool it already called once
- *   (e.g. after losing track of a prior call, or via prompt injection through ordinary operator
- *   content). Left human-UI-only.
- *
- * How it relates to the project:
- * A host's own tool-registration layer maps these entries into `ToolRegistration`s (see
- * `tool-registrations.ts`). Unlike Forms/Identity/Widgets, `menu-service.ts`'s functions perform NO
- * internal `authorize()` call of their own (confirmed: `CreateMenuDeps`/`UpdateMenuTreeDeps`/
- * `AssignLocationDeps` carry no `authorize` field) — every admin HTTP route a host builds is expected
- * to check `deps.authorize(...)` inline, before calling the service function (mirrors `media`'s
- * identical gap, see `media/agent-tools.ts`'s header). `tool-registrations.ts` therefore performs
- * that SAME inline `authorize()` call itself (the identical permission string and `entityType:
- * "menu"` the HTTP route uses) rather than relying on a domain-layer gate that does not exist for
- * this library.
- *
- * Architectural role:
- * `navigation` domain declaration. Imports only `VALID_TARGET_KINDS`-equivalent constants are not
- * exported from `menu-service.ts` as public data (the target-kind allowlist is enforced, not
- * published, there), so the target schema below is hand-authored against `types.ts`'s `NavTarget`
- * union and cross-checked by this catalog's own contract test rather than imported.
- */
-export type AgentToolSideEffect = "none" | "mutates-durable-state" | "mints-token";
-export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
-export interface AgentToolDefinition {
-    name: string;
-    description: string;
-    sideEffects: AgentToolSideEffect;
-    authorization: {
-        permission: string;
-    };
-    actorClassRule?: AgentToolActorClassRule;
-    /**
-     * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
-     * (a host's own tool-registration layer, which refuses to wire any tool lacking one).
-     *
-     * Deliberately not widened to `| undefined` (unlike most optional fields in this port) — this
-     * type flows into `core/tools/registration-kit.ts`'s `WirableToolDefinition`, which declares both
-     * this field and `actorClassRule` below without `| undefined`. Widening only this catalog's copy
-     * would make it structurally incompatible with that shared interface under
-     * `exactOptionalPropertyTypes`, which is exactly what identity's own `agent-tools.ts` avoids for
-     * the same reason.
-     */
-    inputSchema?: Readonly<Record<string, unknown>>;
-}
+import type { AgentToolDefinition } from "@jini-ai/core";
 /**
  * The Navigation domain's fixed agent-tool catalog — the 5 operations a host's admin HTTP surface
  * (`server/routes/admin/menus/*.ts`) exposes that are safe to wrap, out of its 6 total (see file

package/dist/navigation/agent-tools.js

@@ -56,6 +56,17 @@
  * union and cross-checked by this catalog's own contract test rather than imported.
  */
 import { ALLOWED_HREF_SHAPES_DESCRIPTION } from "./menu-service.js";
+/**
+   * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+   * (a host's own tool-registration layer, which refuses to wire any tool lacking one).
+   *
+   * Deliberately not widened to `| undefined` (unlike most optional fields in this port) — this
+   * type flows into `@jini-ai/core`'s `registration-kit.ts`'s `AgentToolDefinition`, which declares both
+   * this field and `actorClassRule` below without `| undefined`. Widening only this catalog's copy
+   * would make it structurally incompatible with that shared interface under
+   * `exactOptionalPropertyTypes`, which is exactly what identity's own `agent-tools.ts` avoids for
+   * the same reason.
+   */
 const MENU_ID_SCHEMA = {
     type: "string",
     description: "The menu's id, as returned by menus_list_menus, menus_get_menu, or menus_create_menu.",
@@ -152,7 +163,7 @@ const ITEMS_TREE_SCHEMA = {
 export const menusAgentToolCatalog = [
     {
         name: "menus_list_menus",
-        description: "Lists every menu in the workspace (id, slug, title, status, item tree, locations, version). Read-only.",
+        description: "Lists every menu in the workspace (id, slug, title, status, item tree, locations, version). Read-only. To delete a menu, use trash_item with entityType 'menu' (it moves to the Trash and can be restored).",
         sideEffects: "none",
         authorization: { permission: "admin.menus.read" },
         inputSchema: {
@@ -177,7 +188,8 @@ export const menusAgentToolCatalog = [
     {
         name: "menus_create_menu",
         description: "Creates a new menu in 'draft' status with no location assigned yet — it has no effect on the live site until " +
-            "menus_assign_location binds it somewhere. Rejects a duplicate slug within the workspace.",
+            "menus_assign_location binds it somewhere. Rejects a duplicate slug within the workspace. " +
+            "To delete a menu, use trash_item with entityType 'menu' (it moves to the Trash and can be restored).",
         sideEffects: "mutates-durable-state",
         authorization: { permission: "admin.menus.create" },
         inputSchema: {
@@ -195,7 +207,7 @@ export const menusAgentToolCatalog = [
         name: "menus_update_menu_tree",
         description: "Replaces an existing menu's whole item tree (and optionally its title/slug) in one version-guarded write. " +
             "Always a whole-tree replace — there is no per-item patch operation, so the submitted tree must include every " +
-            "item the menu keeps.",
+            "item the menu keeps. To delete a menu, use trash_item with entityType 'menu' (it moves to the Trash and can be restored).",
         sideEffects: "mutates-durable-state",
         authorization: { permission: "admin.menus.update" },
         inputSchema: {

package/dist/navigation/contracts.d.ts

@@ -10,7 +10,7 @@
  *
  * INTERFACES + DATA CATALOGS ONLY. No feature logic.
  */
-import type { UUID } from "../core/ports.js";
+import type { UUID } from "@jini-ai/core/primitives";
 import type { NavItemNode, NavLocationKey, NavMenuEntry } from "./types.js";
 /**
  * The `admin.menus.*` permission strings (renamed

package/dist/navigation/index.d.ts

@@ -9,7 +9,7 @@ export { NAV_MENU_CONTENT_TYPE, NAV_FIELD_NAMESPACE, NAV_DOC_TYPE } from "./type
 export type { NavLocationBindingRepoPort, NavResolveContext, NavTargetResolver, NavMenuReadModel, NavLocationRegistry, } from "./ports.js";
 export type { NavigationPermission, CreateMenuInput, UpdateMenuInput, AssignLocationInput, UnassignLocationInput, DeleteMenuInput, NavigationEventName, NavMenuChangedPayload, NavLocationChangedPayload, NavigationHookName, NavigationAiTool, NavWhereUsedResult, } from "./contracts.js";
 export { NAVIGATION_PERMISSIONS, NAVIGATION_EVENTS, NAVIGATION_HOOKS, NAVIGATION_AI_TOOLS, } from "./contracts.js";
-export { createNavMenuReadModel, type NavMenuReadModelDeps } from "./read-model.js";
+export { createNavMenuReadModel, type NavMenuReadModelDeps, type NavMenuReadModelOptions } from "./read-model.js";
 /**
  * `MenuRepoPort` is navigation-owned (not part of the frozen `ports.ts` ADR surface — see
  * `repo.memory.ts`'s file header for why) but is a real public contract: a host's own SQLite
@@ -29,7 +29,7 @@ export { createMenu, updateMenuTree, assignLocation, deleteMenu, validateAndClon
 export { resolveForLocation, resolveMenuDoc, type ResolveTargetHrefFn, type ResolvedTargetHref, type ResolveForLocationDeps, type ResolveForLocationServiceInput, type ResolveForLocationRequired, type ResolveForLocationOptional, } from "./resolver.js";
 export { rebuildNavLocationBindings, type RebuildNavLocationBindingsDeps, type RebuildNavLocationBindingsResult, } from "./reconcile.js";
 /** The agent-tool surface for this domain (see `agent-tools.ts` for what is deliberately omitted). */
-export { menusAgentToolCatalog, type AgentToolDefinition as NavigationAgentToolDefinition, type AgentToolSideEffect as NavigationAgentToolSideEffect, type AgentToolActorClassRule as NavigationAgentToolActorClassRule, } from "./agent-tools.js";
+export { menusAgentToolCatalog, } from "./agent-tools.js";
 /**
  * The agent-tool wiring for this domain.
  *

package/dist/navigation/menu-service.d.ts

@@ -1,12 +1,22 @@
-import type { ClockPort, IdGeneratorPort, OutboxPort, UUID } from "../core/ports.js";
+import type { Clock, IdGenerator, UUID } from "@jini-ai/core/primitives";
+import type { OutboxPort } from "../core/ports.js";
 import type { MenuRepoPort } from "./repo.memory.js";
 import type { NavLocationBindingRepoPort } from "./ports.js";
 import { type NavItemNode, type NavLocationBindingRow, type NavLocationKey, type NavMenuEntry } from "./types.js";
 export declare class MenuNotFoundError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 export declare class MenuValidationError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 export declare class MenuConflictError extends Error {
+    constructor({ message }: {
+        message: string;
+    }, optionalArgs?: ErrorOptions);
 }
 /**
  * The 409-style purge rejection: hard delete is blocked while the menu is
@@ -16,7 +26,10 @@ export declare class MenuConflictError extends Error {
  */
 export declare class MenuLocationBoundError extends MenuConflictError {
     readonly boundLocations: readonly NavLocationKey[];
-    constructor(message: string, boundLocations: readonly NavLocationKey[]);
+    constructor(requiredArgs: {
+        message: string;
+        boundLocations: readonly NavLocationKey[];
+    }, optionalArgs?: Record<string, never>);
 }
 /** Default max nesting depth (root = depth 1). Configurable. */
 export declare const DEFAULT_MAX_TREE_DEPTH = 5;
@@ -25,7 +38,7 @@ export declare const DEFAULT_MAX_ITEM_COUNT = 500;
 /**
  * The CANONICAL href allowlist for an author-authored link — same accepted shapes (`#…`, same-origin
  * `/…`, `http(s)://`, `mailto:`) as the host's render-time `safeHref` in `render.ts` and its
- * `features/theme/static-render.ts` duplicate. **This is now the single source of truth**: exported
+ * `features/theme/static-render.ts` duplicate. **This is now the single source of truth** exported
  * from this package's public surface (`navigation/index.ts` -> `@jini-ai/cms/navigation`) so the
  * dependency runs the direction that is actually legal — the host already depends on `@jini-ai/cms`, not
  * the reverse — rather than each consumer hand-copying the predicate.
@@ -36,14 +49,14 @@ export declare const DEFAULT_MAX_ITEM_COUNT = 500;
  * `check:boundaries` no-deep-import concern is NOT what blocks it: `render.ts` already imports
  * `@jini-ai/cms/core` today, and `features/theme` already imports `@jini-ai/cms/core` too, so both
  * call sites may legally import `@jini-ai/cms/navigation` directly — verified by grep, not assumed).
- * Until that follow-up lands, `apps/website/development/scripts/check-menu-href-allowlist-sync.ts`
+ * Until that follow-up lands, the host's menu href allowlist sync check
  * behaviorally gates the three copies against the same adversarial table so a divergence fails CI
  * instead of drifting silently.
  *
- * Replaced (this change) a `URL_SCHEME_DENYLIST` (`startsWith` on a lowercased, `.trim()`ed string)
+ * Replaced (this change) a `URL_SCHEME_DENYLIST` (`startsWith` on a lowercased, `.trim`ed string)
  * that failed open: the WHATWG `URL` parser strips TAB/LF/CR from ANYWHERE in the input and folds a
- * leading backslash to `/` for `http(s)`, so `"java\tscript:alert(1)"`, `" javascript:alert(1)"`,
- * `"file:///etc/passwd"`, `"blob:…"`, `"about:blank"`, `"//evil.example"` (protocol-relative), and
+ * leading backslash to `/` for `http(s)`, so `"java\tscript:alert"`, `" javascript:alert"`,
+ * `"file:// etc/passwd"`, `"blob:…"`, `"about:blank"`, `"//evil.example"` (protocol-relative), and
  * `"/\evil.example"` all resolved to a dangerous or off-origin target while never matching any
  * `startsWith` prefix in the old list. An allowlist closes the whole bypass class at once (case,
  * embedded control characters, and scheme are all irrelevant to an allowlist the same way) rather
@@ -58,11 +71,13 @@ export declare const DEFAULT_MAX_ITEM_COUNT = 500;
  * hrefs written through the host's admin editor.
  *
  * @param rawHref - The href to check, already confirmed non-empty by `validateTarget`. Any string is
- *   otherwise a valid input — this function performs no other precondition checks.
+ * otherwise a valid input — this function performs no other precondition checks.
  * @returns `true` when `rawHref` passes the allowlist, `false` otherwise.
- * @complexity O(1) — a handful of string checks plus one `URL` construction on the `/…` branch.
+ * @complexity O — a handful of string checks plus one `URL` construction on the `/…` branch.
  */
-export declare function isAllowedHref(rawHref: string): boolean;
+export declare function isAllowedHref({ rawHref }: {
+    rawHref: string;
+}, _optional?: Record<string, never>): boolean;
 /**
  * Human-readable description of {@link isAllowedHref}'s accepted shapes — the single source of truth
  * for both `validateTarget`'s rejection message below and `agent-tools.ts`'s published JSON Schema
@@ -80,31 +95,33 @@ export interface TreeValidationLimits {
  *
  * Checks (total/bounded validation + target integrity):
  * - `items` (and every `children` array) is actually an array, and every node
- *   in it is a non-null object — untrusted JSON bodies can carry `null`
- *   entries or a non-array `items`/`children`, which must reject as a
- *   `MenuValidationError`, not throw an uncaught `TypeError`;
+ * in it is a non-null object — untrusted JSON bodies can carry `null`
+ * entries or a non-array `items`/`children`, which must reject as a
+ * `MenuValidationError`, not throw an uncaught `TypeError`;
  * - every node has a non-empty `id`, unique across the whole tree (id
- *   stability is a caller responsibility — see `updateMenuTree` doc for the
- *   simplification this build accepts);
+ * stability is a caller responsibility — see `updateMenuTree` doc for the
+ * simplification this build accepts);
  * - nesting depth stays within `maxDepth`;
  * - total item count stays within `maxItemCount`;
  * - every node has a `target` object (a missing/`null` `target` rejects
- *   rather than crashing) whose `kind` is one of the four v1 kinds — reserved
- *   kinds (`dynamicQuery`, `content`) are rejected with a clear "not yet"
- *   error rather than silently accepted;
+ * rather than crashing) whose `kind` is one of the four v1 kinds — reserved
+ * kinds (`dynamicQuery`, `content`) are rejected with a clear "not yet"
+ * error rather than silently accepted;
  * - `url` targets require a non-empty string `href` and pass an origin/scheme
- *   ALLOWLIST (`#…`, same-origin `/…`, `http(s)://`, `mailto:` — see
- *   {@link isAllowedHref}), not a scheme denylist.
+ * ALLOWLIST (`#…`, same-origin `/…`, `http(s)://`, `mailto:` — see
+ * {@link isAllowedHref}), not a scheme denylist.
  *
  * @complexity O(n) over total node count for one full walk; no per-node
  * backtracking. Space is O(n) for the cloned tree plus O(n) for the id set.
  * @overallScore 100
  */
-export declare function validateAndCloneTree(items: readonly NavItemNode[], limits?: TreeValidationLimits): NavItemNode[];
+export declare function validateAndCloneTree({ items }: {
+    items: readonly NavItemNode[];
+}, limits?: TreeValidationLimits): NavItemNode[];
 export interface CreateMenuDeps {
     repo: MenuRepoPort;
-    clock: ClockPort;
-    idGen: IdGeneratorPort;
+    clock: Clock;
+    idGen: IdGenerator;
     /** Enqueues `navigation.menu.created` after a successful save. */
     outbox: OutboxPort;
 }
@@ -142,9 +159,9 @@ export declare function createMenu(required: CreateMenuRequired, optional?: Crea
 }>;
 export interface UpdateMenuTreeDeps {
     repo: MenuRepoPort;
-    clock: ClockPort;
+    clock: Clock;
     /** Not previously present on this deps bag — needed to mint the outbox event's id. */
-    idGen: IdGeneratorPort;
+    idGen: IdGenerator;
     /** Enqueues `navigation.menu.updated` after a successful save. */
     outbox: OutboxPort;
 }
@@ -176,7 +193,7 @@ export interface UpdateMenuTreeOptional {
  * previous tree and is deferred — a caller-discipline requirement for now,
  * not a runtime-enforced invariant.
  *
- * @complexity O(n) in the new tree size for validation; O(1) additional repo
+ * @complexity O(n) in the new tree size for validation; O additional repo
  * calls (one read, at most one slug-uniqueness read, one write).
  * @overallScore 90
  * @findings Medium: id-stability across edits (ids not renumbered on survive)
@@ -191,9 +208,9 @@ export declare function updateMenuTree(required: UpdateMenuTreeRequired, optiona
 export interface AssignLocationDeps {
     repo: MenuRepoPort;
     bindingRepo: NavLocationBindingRepoPort;
-    clock: ClockPort;
+    clock: Clock;
     /** Not previously present on this deps bag — needed to mint outbox event ids. */
-    idGen: IdGeneratorPort;
+    idGen: IdGenerator;
     /** Enqueues `navigation.location.assigned` (+ `.unassigned` on reassignment). */
     outbox: OutboxPort;
 }
@@ -229,7 +246,7 @@ export interface AssignLocationOptional {
  * transaction machinery — do not copy this sequencing pattern into code that
  * has real transactions available.
  *
- * @complexity O(1) repo calls (bounded: at most two menu reads/writes plus one
+ * @complexity O repo calls (bounded: at most two menu reads/writes plus one
  * binding upsert), independent of workspace size.
  * @overallScore 90
  * @findings Medium: no rollback across the two writes (menu save, then
@@ -246,9 +263,9 @@ export declare function assignLocation(required: AssignLocationRequired, _option
 export interface DeleteMenuDeps {
     repo: MenuRepoPort;
     bindingRepo: NavLocationBindingRepoPort;
-    clock: ClockPort;
+    clock: Clock;
     /** Not previously present on this deps bag — needed to mint outbox event ids. */
-    idGen: IdGeneratorPort;
+    idGen: IdGenerator;
     /** Enqueues `navigation.menu.updated` (trash) or `navigation.menu.deleted` (purge); nothing on a blocked purge. */
     outbox: OutboxPort;
 }
@@ -267,17 +284,17 @@ export interface DeleteMenuOptional {
 /**
  * Deletion ladder (mirrors the media library's):
  * 1. First call on a non-trashed menu **soft-deletes** it (`status: 'trash'`,
- *    revisioned) and returns — no purge yet.
- * 2. A second call on an already-trashed menu attempts the **hard purge**. If
- *    the menu is still bound to any location, purge is rejected with
- *    `MenuLocationBoundError` (409-style) listing the bound keys, unless
- *    `force` is set — permission-gating that error behind
- *    `navigation.delete.force` is the caller's (gateway's) job, not this
- *    function's; this function only enforces the *shape* of the guard.
+ * revisioned) and returns — no purge yet.
+ * 2. A second call on an already-trashed menu attempts the **hard purge** If
+ * the menu is still bound to any location, purge is rejected with
+ * `MenuLocationBoundError` (409-style) listing the bound keys, unless
+ * `force` is set — permission-gating that error behind
+ * `navigation.delete.force` is the caller's (gateway's) job, not this
+ * function's; this function only enforces the *shape* of the guard.
  * 3. On a successful purge, the menu row and all of its location bindings are
- *    removed.
+ * removed.
  *
- * @complexity O(1) repo calls; O(k) bindings scanned where k = locations this
+ * @complexity O repo calls; O(k) bindings scanned where k = locations this
  * menu holds (small, bounded by registered locations).
  * @overallScore 100
  */