@dotcms/ai 26.10.20-1 → 26.10.21-1

package/src/adapter/context.d.ts

@@ -36,6 +36,17 @@ export interface DotCMSContext {
     languages: LanguageSummary[];
     currentUser: CurrentUserSummary | null;
 }
+/**
+ * The endpoints loading instance context reads — all `GET`. Exported as the one source of
+ * truth for anything that must permit the context load: a tool's own allow-list names these
+ * rather than repeating the paths, so a loader that changes its endpoint changes them too.
+ */
+export declare const CONTEXT_PATHS: {
+    readonly contentTypes: "/api/v1/contenttype";
+    readonly sites: "/api/v1/site";
+    readonly languages: "/api/v2/languages";
+    readonly currentUser: "/api/v1/users/current";
+};
 /**
  * Load a minimal snapshot of dotCMS instance context for sandbox injection.
  * Each loader is independent — a failure in one does not poison the others.

package/src/adapter/request-core.d.ts

@@ -13,6 +13,13 @@ interface FileFieldDescriptor {
     type: string;
     data?: string;
     url?: string;
+    blob?: Blob;
+}
+/** What a response-body sink is told about the body it receives. */
+export interface ResponseBodyInfo {
+    contentType: string;
+    /** From `Content-Length`, when the server sent one. */
+    contentLength?: number;
 }
 type FormDataFieldValue = string | FileFieldDescriptor;
 export interface RequestOptions {
@@ -23,16 +30,39 @@ export interface RequestOptions {
     formData?: Record<string, FormDataFieldValue>;
     headers?: Record<string, string>;
     responseType?: 'auto' | 'base64';
+    onBody?: (body: ReadableStream<Uint8Array>, info: ResponseBodyInfo) => Promise<unknown>;
 }
 /**
  * A policy hook consulted before a request reaches the wire. Return `false` (or throw) to
  * reject. The single place a caller-owned allow-list plugs in — both verbs honor it because
  * both flow through `requestCore`.
+ *
+ * `path` is the RESOLVED path — dot-segments, encoded dots and backslashes already collapsed
+ * the way the URL that is sent will collapse them — so a policy never has to defend against
+ * `/allowed/../elsewhere` itself.
  */
 export type RequestPolicy = (req: {
     method: string;
     path: string;
 }) => boolean | void;
+/**
+ * Normalize an `allow` setting into the policy the request core consults: a list of paths
+ * (a request is allowed when its resolved path IS one of them or lies UNDER one), or a
+ * predicate used as-is. The one place that meaning is defined, so every caller that accepts
+ * `allow` reads it the same way.
+ *
+ * Matching is by whole segment, never by raw `startsWith`: `/api/v1/content` allows
+ * `/api/v1/content` and `/api/v1/content/abc`, but not `/api/v1/contenttype`. As a string
+ * prefix it allowed every endpoint whose name happened to begin the same way. A trailing
+ * slash on an entry changes nothing: `/api/v1/page/` and `/api/v1/page` mean the same, and
+ * `'/'` is the explicit way to allow every path.
+ *
+ * An entry that is not a path (`''`, blank, relative, protocol-relative) throws a
+ * `ValidationError` here, when the runtime or tool is created. This is a security boundary,
+ * so a malformed entry must fail closed and loudly: `''` used to match every path, so a typo or
+ * an unset variable silently opened the whole API.
+ */
+export declare function toRequestPolicy(allow: string[] | RequestPolicy | undefined): RequestPolicy | undefined;
 /** Host-side context the request core needs. Auth lives here, never in the caller's code. */
 export interface RequestCoreContext {
     baseUrl: string;

package/src/adapter.d.ts

@@ -0,0 +1 @@
+export * from './adapter/index';

package/src/runtime.d.ts

@@ -2,8 +2,9 @@ import { type RequestCallEvent, type RequestOptions, type RequestPolicy } from '
 import type { DotCMSContext } from './adapter/context';
 import type { SandboxResult } from './sandbox/types';
 /**
- * Policy controlling which requests are permitted. Either a list of allowed path prefixes
- * (a request is allowed if its path starts with any entry) or a predicate consulted per call.
+ * Policy controlling which requests are permitted. Either a list of allowed paths (a request
+ * is allowed if its path is an entry or lies under one, matched by whole segment, so
+ * `/api/v1/content` does not allow `/api/v1/contenttype`) or a predicate consulted per call.
  * Both verbs honor it, because both flow through the one shared request core.
  */
 export type RuntimeAllow = string[] | RequestPolicy;
@@ -62,11 +63,11 @@ export interface DotCMSRuntime {
 export declare function createRuntime(config: DotCMSRuntimeConfig): DotCMSRuntime;
 export { defineAdapter, describeAdapterForLLM } from './sandbox/define-adapter';
 export type { AdapterContext, AdapterDef, AdapterMethodDef, DefinedAdapter } from './sandbox/define-adapter';
-export { DotCMSError, ValidationError, PolicyError, HttpError, TimeoutError, AbortError, SandboxError, RuntimeError, isDotCMSError, serializeError } from './sandbox/errors';
+export { DotCMSError, ValidationError, PolicyError, HttpError, NetworkError, TimeoutError, AbortError, SandboxError, RuntimeError, isDotCMSError, serializeError } from './sandbox/errors';
 export type { DotCMSErrorCode, SerializedDotCMSError } from './sandbox/errors';
 export type { SandboxResult, SandboxResultError } from './sandbox/types';
 export { formatSandboxResult } from './sandbox/format-result';
 export type { FormatSandboxResultOptions } from './sandbox/format-result';
 export { isBinaryResponseEnvelope } from './adapter/request-core';
-export type { BinaryResponseEnvelope, RequestOptions, RequestCallEvent } from './adapter/request-core';
+export type { BinaryResponseEnvelope, RequestOptions, RequestCallEvent, ResponseBodyInfo } from './adapter/request-core';
 export type { DotCMSContext, ContentTypeSummary, SiteSummary, LanguageSummary, CurrentUserSummary } from './adapter/context';

package/src/sandbox/errors.d.ts

@@ -10,7 +10,7 @@
  * the worker→host serialization boundary (a thrown error becomes `{ name, message, stack }`
  * by default; these types preserve `code` and the structured detail too).
  */
-export type DotCMSErrorCode = 'VALIDATION' | 'POLICY' | 'HTTP' | 'TIMEOUT' | 'ABORT' | 'SANDBOX' | 'RUNTIME';
+export type DotCMSErrorCode = 'VALIDATION' | 'POLICY' | 'HTTP' | 'NETWORK' | 'TIMEOUT' | 'ABORT' | 'SANDBOX' | 'RUNTIME';
 /** Serializable shape every DotCMSError flattens to (and that crosses the worker boundary). */
 export interface SerializedDotCMSError {
     name: string;
@@ -35,6 +35,7 @@ export declare abstract class DotCMSError extends Error {
 }
 /** Adapter input failed validation, or request options were malformed. */
 export declare class ValidationError extends DotCMSError {
+    readonly name = "ValidationError";
     readonly code: "VALIDATION";
     /** Field-level issues, when the source was a Zod (or similar) schema. */
     readonly issues?: unknown[];
@@ -43,6 +44,7 @@ export declare class ValidationError extends DotCMSError {
 }
 /** The allow-list / policy rejected the call before it reached the network. */
 export declare class PolicyError extends DotCMSError {
+    readonly name = "PolicyError";
     readonly code: "POLICY";
     readonly method: string;
     readonly path: string;
@@ -51,6 +53,7 @@ export declare class PolicyError extends DotCMSError {
 }
 /** dotCMS responded with a non-2xx status. Carries the status and the (text) body. */
 export declare class HttpError extends DotCMSError {
+    readonly name = "HttpError";
     readonly code: "HTTP";
     readonly status: number;
     readonly statusText: string;
@@ -58,8 +61,24 @@ export declare class HttpError extends DotCMSError {
     constructor(status: number, statusText: string, body: string);
     detail(): Record<string, unknown>;
 }
+/**
+ * The request never got a response — the connection was refused or reset, the host did not
+ * resolve, the socket timed out. Distinct from `HttpError` (the instance answered, with an
+ * error) because the two call for opposite reactions: this one is usually worth retrying.
+ */
+export declare class NetworkError extends DotCMSError {
+    readonly name = "NetworkError";
+    readonly code: "NETWORK";
+    readonly method: string;
+    readonly path: string;
+    /** The platform's own reason, e.g. `ECONNREFUSED`, when it gave one. */
+    readonly reason?: string;
+    constructor(method: string, path: string, cause: unknown);
+    detail(): Record<string, unknown>;
+}
 /** A timeout elapsed (sandbox wall-clock, per-adapter-call, or context load). */
 export declare class TimeoutError extends DotCMSError {
+    readonly name = "TimeoutError";
     readonly code: "TIMEOUT";
     readonly timeoutMs?: number;
     constructor(message: string, timeoutMs?: number);
@@ -67,10 +86,12 @@ export declare class TimeoutError extends DotCMSError {
 }
 /** The call was aborted in-flight (typically because the sandbox timed out). */
 export declare class AbortError extends DotCMSError {
+    readonly name = "AbortError";
     readonly code: "ABORT";
 }
 /** Model-authored code threw while executing inside the sandbox. */
 export declare class SandboxError extends DotCMSError {
+    readonly name = "SandboxError";
     readonly code: "SANDBOX";
     /** The original error's name (e.g. "TypeError") as seen inside the sandbox. */
     readonly originalName?: string;
@@ -79,6 +100,7 @@ export declare class SandboxError extends DotCMSError {
 }
 /** Catch-all for runtime-internal failures that don't fit a more specific type. */
 export declare class RuntimeError extends DotCMSError {
+    readonly name = "RuntimeError";
     readonly code: "RUNTIME";
 }
 /** Type guard for any error in the hierarchy. */

package/src/sandbox/index.d.ts

@@ -13,7 +13,7 @@ export { formatSandboxResult } from './format-result';
 export type { FormatSandboxResultOptions } from './format-result';
 export { defineAdapter, isDefinedAdapter, describeAdapterForLLM } from './define-adapter';
 export type { AdapterContext, AdapterDef, AdapterMethodDef, DefinedAdapter, RequestLike } from './define-adapter';
-export { DotCMSError, ValidationError, PolicyError, HttpError, TimeoutError, AbortError, SandboxError, RuntimeError, isDotCMSError, serializeError } from './errors';
+export { DotCMSError, ValidationError, PolicyError, HttpError, NetworkError, TimeoutError, AbortError, SandboxError, RuntimeError, isDotCMSError, serializeError } from './errors';
 export type { DotCMSErrorCode, SerializedDotCMSError } from './errors';
 export type { Adapter, AdapterMethod, AdapterMethodParameter, SandboxConfig, SandboxResourceLimits, SandboxResult, SandboxResultError, ExecutionContext } from './types';
 export interface CreateSandboxConfig {

package/src/sandbox.d.ts

@@ -0,0 +1 @@
+export * from './sandbox/index';

package/src/spec.d.ts

@@ -0,0 +1 @@
+export * from './spec/index';

package/src/tools/definitions/download-assets.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { type DownloadAssetsManifest } from '../operations/download-assets';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { AssetToolOptions, DotCMSTool } from '../toolkit/types';
+declare const definition: import("../toolkit/create-tool").ToolDefinition<z.ZodObject<{
+    path: z.ZodString;
+    kind: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
+        folder: "folder";
+        asset: "asset";
+    }>>;
+    dest: z.ZodString;
+    recursive: z.ZodDefault<z.ZodBoolean>;
+    overwrite: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        skip: "skip";
+        overwrite: "overwrite";
+    }>>;
+    include: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, DownloadAssetsManifest, AssetToolOptions>;
+/**
+ * The `download_assets` tool: streams dotCMS file assets to a local directory — the bytes
+ * never pass through the model. Needs Node or Bun. Resolves to a {@link DownloadAssetsManifest}.
+ * `options.root` bounds which local directories the model may write into.
+ */
+export declare function downloadAssetsTool(connection: DotCMSConnection, options: AssetToolOptions): DotCMSTool<typeof definition.inputSchema, DownloadAssetsManifest>;
+export {};

package/src/tools/definitions/execute.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { CodeToolResult } from '../toolkit/results';
+import type { DotCMSTool, ExecuteToolOptions } from '../toolkit/types';
+/** Sandbox wall-clock timeout for `execute` when the factory is given none. */
+export declare const DEFAULT_EXECUTE_TIMEOUT_MS = 45000;
+declare const input: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The `execute` tool: the model writes JavaScript, and it runs in the sandbox against the
+ * dotCMS API. Resolves to `{ result }`, the capped text of the code's result (or its error).
+ */
+export declare function executeTool(connection: DotCMSConnection, options?: ExecuteToolOptions): DotCMSTool<typeof input, CodeToolResult>;
+export {};

package/src/tools/definitions/page-create.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { type CreatePageManifest } from '../operations/page-create';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { DotCMSTool, RequestToolOptions } from '../toolkit/types';
+declare const definition: import("../toolkit/create-tool").ToolDefinition<z.ZodObject<{
+    site: z.ZodString;
+    urlPath: z.ZodString;
+    title: z.ZodString;
+    template: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    extraFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    friendlyName: z.ZodOptional<z.ZodString>;
+    pageTitle: z.ZodOptional<z.ZodString>;
+    languageId: z.ZodDefault<z.ZodNumber>;
+    cacheTtl: z.ZodDefault<z.ZodString>;
+    sortOrder: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, CreatePageManifest, RequestToolOptions>;
+/**
+ * The `page_create` tool: creates and publishes a page, creating its parent folder first so
+ * the URL lands where it was asked for. Resolves to a {@link CreatePageManifest}.
+ */
+export declare function pageCreateTool(connection: DotCMSConnection, options?: RequestToolOptions): DotCMSTool<typeof definition.inputSchema, CreatePageManifest>;
+export {};

package/src/tools/definitions/page-place-content.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { type PagePlaceContentManifest } from '../operations/page-place-content';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { DotCMSTool, RequestToolOptions } from '../toolkit/types';
+declare const definition: import("../toolkit/create-tool").ToolDefinition<z.ZodObject<{
+    path: z.ZodString;
+    site: z.ZodOptional<z.ZodString>;
+    slots: z.ZodArray<z.ZodObject<{
+        slot: z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            container: z.ZodString;
+            instance: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        contentlets: z.ZodArray<z.ZodString>;
+        op: z.ZodOptional<z.ZodEnum<{
+            remove: "remove";
+            set: "set";
+            append: "append";
+        }>>;
+    }, z.core.$strict>>;
+    variantName: z.ZodOptional<z.ZodString>;
+    languageId: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        replace: "replace";
+        merge: "merge";
+    }>>;
+}, z.core.$strip>, PagePlaceContentManifest, RequestToolOptions>;
+/**
+ * The `page_place_content` tool: places contentlets into a page's slots while preserving
+ * every slot it was not asked to touch. Resolves to a {@link PagePlaceContentManifest}.
+ */
+export declare function pagePlaceContentTool(connection: DotCMSConnection, options?: RequestToolOptions): DotCMSTool<typeof definition.inputSchema, PagePlaceContentManifest>;
+export {};

package/src/tools/definitions/page-verify.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { type VerifyPageManifest } from '../operations/page-verify';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { DotCMSTool, RequestToolOptions } from '../toolkit/types';
+declare const definition: import("../toolkit/create-tool").ToolDefinition<z.ZodObject<{
+    path: z.ZodString;
+    site: z.ZodOptional<z.ZodString>;
+    languageId: z.ZodOptional<z.ZodNumber>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        LIVE: "LIVE";
+        WORKING: "WORKING";
+    }>>;
+    includeHtml: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, VerifyPageManifest, RequestToolOptions>;
+/**
+ * The `page_verify` tool: renders a page and diagnoses each slot — empty, swallowed VTL
+ * error, stale cache, not assembled. Read-only. Resolves to a {@link VerifyPageManifest}.
+ */
+export declare function pageVerifyTool(connection: DotCMSConnection, options?: RequestToolOptions): DotCMSTool<typeof definition.inputSchema, VerifyPageManifest>;
+export {};

package/src/tools/definitions/search.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { CodeToolResult } from '../toolkit/results';
+import type { DotCMSTool } from '../toolkit/types';
+declare const input: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The `search` tool: the model writes JavaScript that explores the bundled OpenAPI spec.
+ * Read-only. Resolves to `{ result }`, the capped text of the code's result (or its error).
+ */
+export declare function searchTool(connection: DotCMSConnection): DotCMSTool<typeof input, CodeToolResult>;
+export {};

package/src/tools/definitions/upload-assets.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { type UploadAssetsManifest } from '../operations/upload-assets';
+import type { DotCMSConnection } from '../toolkit/connection';
+import type { DotCMSTool, UploadToolOptions } from '../toolkit/types';
+declare const definition: import("../toolkit/create-tool").ToolDefinition<z.ZodObject<{
+    src: z.ZodString;
+    dest: z.ZodString;
+    include: z.ZodOptional<z.ZodString>;
+    publish: z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDefault<z.ZodBoolean>>>;
+    verify: z.ZodDefault<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodDefault<z.ZodBoolean>>>;
+}, z.core.$strip>, UploadAssetsManifest, UploadToolOptions>;
+/**
+ * The `upload_assets` tool: uploads a local directory into dotCMS as file assets — the bytes
+ * never pass through the model. Needs Node or Bun. Resolves to an {@link UploadAssetsManifest}.
+ * `options.root` bounds which local directories the model may read from.
+ *
+ * The model chooses `src`, so the tool is bounded by default: `options.maxFileBytes` (100 MB),
+ * `options.maxFiles` (1,000) and `options.maxScannedEntries` (20,000 entries walked). Each file
+ * is held in memory once while it is sent (`fetch` buffers request bodies), so the file limit
+ * is also the upload's memory bound. Pass `Infinity` to lift any of them.
+ */
+export declare function uploadAssetsTool(connection: DotCMSConnection, options: UploadToolOptions): DotCMSTool<typeof definition.inputSchema, UploadAssetsManifest>;
+export {};

package/src/tools/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@dotcms/ai/tools` — ready-made dotCMS tools for a host's own MCP server or agent.
+ *
+ * Two public layers, the same split as the runtime's two verbs:
+ *  - `definitions/` — the tool factories (`searchTool()`, `pageCreateTool()`, …), the
+ *    model-facing layer. Each returns a plain object shaped for the Vercel AI SDK and the MCP
+ *    TypeScript SDK alike, whose `execute` validates the model's input and never throws.
+ *  - `operations/` — `createPage`, `placeContent`, `verifyPage`, `uploadAssets`,
+ *    `downloadAssets`, the direct layer. Typed options in, typed manifest out, typed errors
+ *    thrown. Use these when YOU write the call; the tools are formatting on top.
+ *
+ * Both are built on `toolkit/`, which is internal. See ./README.md for what goes where.
+ *
+ * This is the top layer of the package: it builds on `@dotcms/ai/runtime`, and nothing below
+ * it may import it (lint-enforced).
+ */
+export { dotcmsConnection } from './toolkit/connection';
+export type { DotCMSConnection, DotCMSConnectionConfig, Resolvable } from './toolkit/connection';
+export { executeTool } from './definitions/execute';
+export { searchTool } from './definitions/search';
+export { pageCreateTool } from './definitions/page-create';
+export { pagePlaceContentTool } from './definitions/page-place-content';
+export { pageVerifyTool } from './definitions/page-verify';
+export { uploadAssetsTool } from './definitions/upload-assets';
+export { downloadAssetsTool } from './definitions/download-assets';
+export type { AnyDotCMSTool, AssetToolOptions, DotCMSTool, DotCMSToolAnnotations, ExecuteToolOptions, RequestToolOptions, UploadToolOptions } from './toolkit/types';
+export { isToolFailure } from './toolkit/tool-runtime';
+export type { ToolFailure, ToolFailureCode } from './toolkit/tool-runtime';
+export type { CodeToolResult, JSONValue, ToolModelOutput } from './toolkit/results';
+export { createPage } from './operations/page-create';
+export type { CreatePageManifest, CreatePageOptions } from './operations/page-create';
+export { placeContent } from './operations/page-place-content';
+export type { PagePlaceContentManifest, PagePlaceContentOptions, PlaceMode, PlaceOp, SlotAddress, SlotAssignment, SlotResult } from './operations/page-place-content';
+export { verifyPage } from './operations/page-verify';
+export type { SlotVerdict, UrlMapResult, VerifyHtmlResult, VerifyMode, VerifyPageManifest, VerifyPageOptions, VerifySlotResult } from './operations/page-verify';
+export { uploadAssets } from './operations/upload-assets';
+export type { UploadAssetsManifest, UploadAssetsOptions } from './operations/upload-assets';
+export { downloadAssets } from './operations/download-assets';
+export type { DownloadAssetsManifest, DownloadAssetsOptions, DownloadKind, OverwriteMode } from './operations/download-assets';
+export type { AssetManifestFailure, AssetManifestFile, AssetManifestSkipped } from './operations/shared/asset-common';

package/src/tools/operations/download-assets.d.ts

@@ -0,0 +1,55 @@
+import { type AssetManifestFailure, type AssetManifestFile, type AssetManifestSkipped } from './shared/asset-common';
+import { type DotCMSRuntime } from '../../runtime';
+import { type Endpoint } from '../toolkit/endpoints';
+/**
+ * Every endpoint `downloadAssets` calls — all reads. The `download_assets` tool enforces
+ * exactly this list, and `download-assets.spec.ts` checks every request against it.
+ */
+export declare const DOWNLOAD_ASSETS_ENDPOINTS: readonly Endpoint[];
+/** What `downloadAssets` does when a destination file already exists. */
+export type OverwriteMode = 'skip' | 'overwrite' | 'error';
+/**
+ * What `path` names. `'asset'` and `'folder'` say so outright. `'auto'` guesses from the last
+ * segment (an extension means an asset) and, when that reading finds nothing, tries the other:
+ * so a folder named `v1.2` and an asset named `robots` both work without the caller knowing.
+ */
+export type DownloadKind = 'auto' | 'asset' | 'folder';
+export interface DownloadAssetsOptions {
+    dotcms: DotCMSRuntime;
+    /**
+     * dotCMS folder or asset path, optionally host-qualified (`//host/path`). A folder is
+     * searched on that one site; a path with no host means the default site.
+     */
+    path: string;
+    /** Whether `path` is one asset or a folder. Default `'auto'`; see {@link DownloadKind}. */
+    kind?: DownloadKind;
+    /** Absolute local directory the files are written into. */
+    dest: string;
+    /** Include files in nested folders. */
+    recursive: boolean;
+    overwrite: OverwriteMode;
+    /** Comma-separated glob filter, e.g. `*.vtl,*.scss`. */
+    include?: string;
+    /**
+     * Directory `dest`, and every file written, must stay inside — after symlinks resolve.
+     * Omit only when YOU chose `dest`; the `download_assets` tool always sets it.
+     */
+    root?: string;
+}
+/** What `downloadAssets` returns — never the file bytes, only where they landed. */
+export interface DownloadAssetsManifest {
+    path: string;
+    dest: string;
+    count: number;
+    bytes: number;
+    files: AssetManifestFile[];
+    failures: AssetManifestFailure[];
+    skipped: AssetManifestSkipped[];
+    warnings: string[];
+}
+/**
+ * Download a dotCMS asset, or every asset under a folder, to a local directory. Relative
+ * paths are preserved, and one failed file is recorded in the manifest rather than aborting
+ * the batch.
+ */
+export declare function downloadAssets(options: DownloadAssetsOptions): Promise<DownloadAssetsManifest>;

package/src/tools/operations/page-create.d.ts

@@ -0,0 +1,81 @@
+import { type DotCMSRuntime } from '../../runtime';
+import { type Endpoint } from '../toolkit/endpoints';
+/**
+ * Every endpoint `createPage` calls — the `page_create` tool enforces exactly this list, and
+ * `page-create.spec.ts` checks every request against it. Add a request, add it here.
+ */
+export declare const PAGE_CREATE_ENDPOINTS: readonly Endpoint[];
+/** The default page content type when the caller does not name one. */
+export declare const DEFAULT_PAGE_CONTENT_TYPE = "htmlpageasset";
+export interface CreatePageOptions {
+    dotcms: DotCMSRuntime;
+    /** Site identifier (UUID) or hostname the page lives on. */
+    site: string;
+    /** Page-relative URL path, e.g. "/books/index" or "/books". The leaf becomes the page url. */
+    urlPath: string;
+    /** Page title. */
+    title: string;
+    /** Template identifier the page renders with. */
+    template: string;
+    /**
+     * Content type for the page — variable or id. Defaults to `htmlpageasset`. Any content type
+     * works as long as its base type is HTMLPAGE (a custom page type may add its own fields).
+     */
+    contentType?: string;
+    /**
+     * Values for content-type fields beyond the common page fields — keyed by field variable.
+     * Required for any user-added required field on a custom page type that has no default value.
+     */
+    extraFields?: Record<string, unknown>;
+    /** Optional friendly name; defaults to `title`. */
+    friendlyName?: string;
+    /** Optional page title (browser <title>); defaults to `title`. */
+    pageTitle?: string;
+    /** Language id. Default 1. */
+    languageId?: number;
+    /** Cache TTL seconds (as dotCMS expects: a string). Default "0". */
+    cacheTtl?: string;
+    /** Sort order. Default 0. */
+    sortOrder?: number;
+}
+export interface CreatePageManifest {
+    /** Identifier of the created page contentlet. */
+    identifier?: string;
+    /** Inode of the created version. */
+    inode?: string;
+    /** The resolved content type variable the page was created as. */
+    contentType: string;
+    /** The folder path the page was placed under (e.g. "/books"). */
+    folder: string;
+    /** The leaf url stored on the page (e.g. "index"). */
+    url: string;
+    /** Full live URL on the site (e.g. "/books/index"). */
+    fullPath: string;
+    /** Site the page lives on. */
+    site: string;
+    /** Whether the page is live after the publish fire. */
+    live: boolean;
+    /**
+     * Set when the page was created but NOT verified live. The page exists; it just may render
+     * blank with no content placed (the two-step trap). Not a hard failure.
+     */
+    warnings: string[];
+}
+/**
+ * Create and publish a dotCMS page in one safe call.
+ *
+ * A "page" is a contentlet whose content type's base type is HTMLPAGE, fired through the generic
+ * workflow endpoint — there is no dedicated create-page endpoint. The content type defaults to
+ * `htmlpageasset` but can be any page type; custom page types may add their own (possibly required)
+ * fields, so we resolve the type and validate against its actual field set before firing.
+ *
+ * This wrapper absorbs the URL-collapse trap: dotCMS silently collapses a page `url` whose parent
+ * folder does not exist down to `/index`, which then 400s against the home page. We split `urlPath`
+ * into folder + leaf, create the folder first, then fire the page with `url: "<leaf>"` and
+ * `hostFolder: <created folder>` so the URL lands where the caller meant.
+ *
+ * This is the THIN tier: it does NOT place content. The page comes up live but blank — content
+ * placement and the re-publish that follows are a separate, explicit step for the caller. The
+ * manifest flags this so a successful create is never mistaken for a fully-populated page.
+ */
+export declare function createPage(options: CreatePageOptions): Promise<CreatePageManifest>;

package/src/tools/operations/page-place-content.d.ts

@@ -0,0 +1,102 @@
+import { type DotCMSRuntime } from '../../runtime';
+import { type Endpoint } from '../toolkit/endpoints';
+/**
+ * Every endpoint `placeContent` calls — the `page_place_content` tool enforces exactly this
+ * list, and `page-place-content.spec.ts` checks every request against it. Add a request, add it
+ * here.
+ */
+export declare const PAGE_PLACE_CONTENT_ENDPOINTS: readonly Endpoint[];
+/** The default variant when the caller does not name one. */
+export declare const DEFAULT_VARIANT = "DEFAULT";
+/** The default language id when the caller does not name one. */
+export declare const DEFAULT_LANGUAGE_ID = 1;
+/** How a slot's contentlet list is combined with the ids the caller supplies. */
+export type PlaceOp = 'append' | 'set' | 'remove';
+/** Whether the tool merges into the page's current content or replaces it wholesale. */
+export type PlaceMode = 'merge' | 'replace';
+/**
+ * How the caller points at a slot. Either the 1-based index into the page's real slots (in layout
+ * order), or a container reference. `instance` (the slot uuid) is optional ONLY when the named
+ * container occupies exactly one slot on the page; otherwise it is required to disambiguate.
+ */
+export type SlotAddress = number | {
+    container: string;
+    instance?: string;
+};
+/** One slot assignment in the multi-slot (`slots[]`) form. */
+export interface SlotAssignment {
+    slot: SlotAddress;
+    contentlets: string[];
+    op?: PlaceOp;
+}
+export interface PagePlaceContentOptions {
+    dotcms: DotCMSRuntime;
+    /** Page URL path (e.g. "/about-us"), host-qualified path, or a page identifier (UUID). */
+    path: string;
+    /**
+     * Site hostname or identifier. Required unless `path` is host-qualified as
+     * `//hostname/path`; the qualified form supplies this value implicitly.
+     */
+    site?: string;
+    /**
+     * One or more slot assignments applied in a single atomic write. Placing content in one slot is
+     * just an array of one: `[{ slot, contentlets }]`.
+     */
+    slots: SlotAssignment[];
+    /** Variant name. Default "DEFAULT". */
+    variantName?: string;
+    /** Language id. Default 1. */
+    languageId?: number;
+    /**
+     * "merge" (default) reads the page's current content and applies the ops on top, preserving every
+     * untouched slot. "replace" treats the supplied slots as the complete desired map — every other
+     * slot on the page is cleared. Both still validate slot existence and return a before/after diff.
+     */
+    mode?: PlaceMode;
+}
+/** The before/after picture of one slot the write touched or preserved. */
+export interface SlotResult {
+    /** Container key as the layout addresses it (path for file containers, id for db containers). */
+    identifier: string;
+    /** Slot instance uuid. */
+    uuid: string;
+    /** Contentlet ids in the slot before the write. */
+    before: string[];
+    /** Contentlet ids in the slot after the write. */
+    after: string[];
+    /** True when before/after differ. */
+    changed: boolean;
+}
+export interface PagePlaceContentManifest {
+    /** Identifier of the page whose content was written. */
+    pageId: string;
+    /** Hostname of the site whose page was updated. */
+    site: string;
+    /** The page's url path. */
+    url: string;
+    /** Variant the write targeted. */
+    variantName: string;
+    /** Language id the write targeted. */
+    languageId: number;
+    /** The effective mode ("merge" or "replace"). */
+    mode: PlaceMode;
+    /** Per-slot before/after for every slot on the page (touched and untouched). */
+    slots: SlotResult[];
+    /** Actionable notices: content loss, net-loss conflict, etc. Empty on a clean happy path. */
+    warnings: string[];
+}
+/**
+ * Place content into a page's container slots without wiping the rest of the page.
+ *
+ * `POST /api/v1/page/{pageId}/content` is a FULL replacement of the page's container-to-contentlet
+ * map: any slot omitted from the body is emptied. A caller that means "add one contentlet to one
+ * slot" but sends only that slot silently clears every other slot. This wrapper absorbs that trap:
+ * it reads the page's current content first, applies the requested op(s) to the addressed slot(s)
+ * only, then POSTs the COMPLETE map back so untouched slots survive.
+ *
+ * It also removes the discovery friction: the caller addresses a slot by index or container name
+ * and we resolve it to the exact `identifier`+`uuid` the endpoint needs — sourced from the page's
+ * real layout, so a typo fails clearly instead of silently doing nothing. The returned manifest
+ * gives a before/after diff per slot and flags any slot that lost content.
+ */
+export declare function placeContent(options: PagePlaceContentOptions): Promise<PagePlaceContentManifest>;