@karmaniverous/jeeves-server-core 0.4.0 → 0.5.0

package/dist/src/catalog/contentSchemas.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Response and request schemas of the content entries (drives, browse, file content, write and mutate, link info, export cache clear, public content), describing what the service's handlers send. Pure.
+ *
+ * @remarks
+ * Field order follows the handlers' output: with strict response
+ * validation the service sends the parsed value, so a schema's key order is
+ * the body's key order. Fields are plain strings (no formats) because they
+ * carry paths, dates and names exactly as the handlers build them.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** One breadcrumb of a file or directory view. */
+export declare const breadcrumbSchema: z.ZodObject<{
+    label: z.ZodString;
+    path: z.ZodString;
+}, z.core.$strip>;
+/** One `drives` row: a configured root. */
+export declare const driveSchema: z.ZodObject<{
+    letter: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+/** `drives` response: the roots the caller may navigate into. */
+export declare const drivesResponseSchema: z.ZodArray<z.ZodObject<{
+    letter: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>>;
+/** One entry of a directory listing. */
+export declare const directoryEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        file: "file";
+        directory: "directory";
+    }>;
+    ext: z.ZodString;
+    size: z.ZodNullable<z.ZodNumber>;
+    mtime: z.ZodNullable<z.ZodString>;
+    itemCount: z.ZodNullable<z.ZodNumber>;
+    shareUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+/** `browse` response for a file: its metadata. */
+export declare const fileMetadataSchema: z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    ext: z.ZodString;
+    size: z.ZodNumber;
+    mtime: z.ZodString;
+}, z.core.$strip>;
+/** `browse` response for a directory: its listing. */
+export declare const directoryListingSchema: z.ZodObject<{
+    path: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+        }>;
+        ext: z.ZodString;
+        size: z.ZodNullable<z.ZodNumber>;
+        mtime: z.ZodNullable<z.ZodString>;
+        itemCount: z.ZodNullable<z.ZodNumber>;
+        shareUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    breadcrumbs: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    isInsider: z.ZodBoolean;
+}, z.core.$strip>;
+/** `browse` response: file metadata or a directory listing. */
+export declare const browseResponseSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"file">;
+    path: z.ZodString;
+    ext: z.ZodString;
+    size: z.ZodNumber;
+    mtime: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    path: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            file: "file";
+            directory: "directory";
+        }>;
+        ext: z.ZodString;
+        size: z.ZodNullable<z.ZodNumber>;
+        mtime: z.ZodNullable<z.ZodString>;
+        itemCount: z.ZodNullable<z.ZodNumber>;
+        shareUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+    breadcrumbs: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    isInsider: z.ZodBoolean;
+}, z.core.$strip>]>;
+/** One heading of a rendered Markdown document. */
+export declare const headingSchema: z.ZodObject<{
+    level: z.ZodNumber;
+    text: z.ZodString;
+    slug: z.ZodString;
+}, z.core.$strip>;
+/**
+ * `fileContent` response. One shape for every file type: `type` says which
+ * fields are present.
+ */
+export declare const fileContentResponseSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        plantuml: "plantuml";
+        text: "text";
+        markdown: "markdown";
+        mermaid: "mermaid";
+        svg: "svg";
+        csv: "csv";
+        image: "image";
+        binary: "binary";
+    }>;
+    content: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    headings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        level: z.ZodNumber;
+        text: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strip>>>;
+    size: z.ZodOptional<z.ZodNumber>;
+    fileName: z.ZodString;
+    breadcrumbs: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strip>>;
+    isInsider: z.ZodBoolean;
+    mtime: z.ZodOptional<z.ZodNumber>;
+    renderAs: z.ZodOptional<z.ZodString>;
+    matchedRules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `fileContent` query, beside the share parameters. */
+export declare const fileContentQuerySchema: z.ZodObject<{
+    raw: z.ZodOptional<z.ZodString>;
+    render_diagrams: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `fileWrite` body. */
+export declare const fileWriteBodySchema: z.ZodObject<{
+    content: z.ZodString;
+}, z.core.$strip>;
+/** `fileWrite` response. */
+export declare const fileWriteResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    path: z.ZodString;
+    size: z.ZodNumber;
+}, z.core.$strip>;
+/** `{ ok: true }`. */
+export declare const okResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/** One available export of a path. */
+export declare const exportLinkSchema: z.ZodObject<{
+    format: z.ZodString;
+    url: z.ZodString;
+}, z.core.$strip>;
+/** `linkInfo` response; only `exists` when the path doesn't exist. */
+export declare const linkInfoResponseSchema: z.ZodObject<{
+    exists: z.ZodBoolean;
+    isDirectory: z.ZodOptional<z.ZodBoolean>;
+    pageUrl: z.ZodOptional<z.ZodString>;
+    rawUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    downloadUrl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    exportLinks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        format: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** `exportCacheClear` response. */
+export declare const exportCacheClearResponseSchema: z.ZodObject<{
+    cleared: z.ZodObject<{
+        exports: z.ZodNumber;
+        diagrams: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/src/catalog/contentSchemas.js

@@ -0,0 +1,195 @@
+import { z } from 'zod';
+
+/**
+ * Response and request schemas of the content entries (drives, browse, file content, write and mutate, link info, export cache clear, public content), describing what the service's handlers send. Pure.
+ *
+ * @remarks
+ * Field order follows the handlers' output: with strict response
+ * validation the service sends the parsed value, so a schema's key order is
+ * the body's key order. Fields are plain strings (no formats) because they
+ * carry paths, dates and names exactly as the handlers build them.
+ *
+ * @packageDocumentation
+ */
+/** One breadcrumb of a file or directory view. */
+const breadcrumbSchema = z.object({
+    /** Display label (a root's label or a path segment). */
+    label: z.string(),
+    /** Browse path of the crumb. */
+    path: z.string(),
+});
+/** One `drives` row: a configured root. */
+const driveSchema = z.object({
+    /** Root id, the first segment of every browse path below it. */
+    letter: z.string(),
+    /** Root label (its filesystem path, or the configured label). */
+    label: z.string(),
+});
+/** `drives` response: the roots the caller may navigate into. */
+const drivesResponseSchema = z.array(driveSchema);
+/** One entry of a directory listing. */
+const directoryEntrySchema = z.object({
+    /** File or directory name. */
+    name: z.string(),
+    /** Entry type. */
+    type: z.enum(['directory', 'file']),
+    /** Lowercase extension with its dot, or empty. */
+    ext: z.string(),
+    /** File size in bytes; null for directories. */
+    size: z.number().nullable(),
+    /** Modification date (`YYYY-MM-DD`), or null when unreadable. */
+    mtime: z.string().nullable(),
+    /** Number of children of a directory; null for files. */
+    itemCount: z.number().nullable(),
+    /**
+     * Deep-share listings only: the entry's own share URL, or null when it
+     * may not be opened.
+     */
+    shareUrl: z.string().nullable().optional(),
+});
+/** `browse` response for a file: its metadata. */
+const fileMetadataSchema = z.object({
+    /** Always `file`. */
+    type: z.literal('file'),
+    /** The browse path asked for. */
+    path: z.string(),
+    /** Lowercase extension with its dot, or empty. */
+    ext: z.string(),
+    /** Size in bytes. */
+    size: z.number(),
+    /** Modification date (`YYYY-MM-DD`). */
+    mtime: z.string(),
+});
+/** `browse` response for a directory: its listing. */
+const directoryListingSchema = z.object({
+    /** The browse path asked for. */
+    path: z.string(),
+    /** Entries the caller may see, directories first. */
+    entries: z.array(directoryEntrySchema),
+    /** Breadcrumbs (outsiders see only those inside their share). */
+    breadcrumbs: z.array(breadcrumbSchema),
+    /** Whether the caller is an insider. */
+    isInsider: z.boolean(),
+});
+/** `browse` response: file metadata or a directory listing. */
+const browseResponseSchema = z.union([
+    fileMetadataSchema,
+    directoryListingSchema,
+]);
+/** One heading of a rendered Markdown document. */
+const headingSchema = z.object({
+    /** Heading level (1-6). */
+    level: z.number(),
+    /** Heading text. */
+    text: z.string(),
+    /** Anchor slug. */
+    slug: z.string(),
+});
+/**
+ * `fileContent` response. One shape for every file type: `type` says which
+ * fields are present.
+ */
+const fileContentResponseSchema = z.object({
+    /** How the file is shown. */
+    type: z.enum([
+        'markdown',
+        'mermaid',
+        'plantuml',
+        'svg',
+        'csv',
+        'text',
+        'image',
+        'binary',
+    ]),
+    /** File text (Markdown, diagram, SVG, CSV and text files). */
+    content: z.string().optional(),
+    /** Rendered HTML; null when a diagram could not be rendered. */
+    html: z.string().nullable().optional(),
+    /** Heading outline of rendered Markdown. */
+    headings: z.array(headingSchema).optional(),
+    /** Size in bytes (binary files). */
+    size: z.number().optional(),
+    /** File name. */
+    fileName: z.string(),
+    /** Breadcrumbs (outsiders see only those inside their share). */
+    breadcrumbs: z.array(breadcrumbSchema),
+    /** Whether the caller is an insider. */
+    isInsider: z.boolean(),
+    /** Modification time (Unix ms) of rendered Markdown. */
+    mtime: z.number().optional(),
+    /** Format jeeves-watcher rendered the file as (watcher-rendered files). */
+    renderAs: z.string().optional(),
+    /** Watcher rules that matched (watcher-rendered files). */
+    matchedRules: z.array(z.string()).optional(),
+    /**
+     * Document title (#262): a Markdown document's front matter `title`, else
+     * the file name. `fileContent` always sends it; `publicContent` doesn't.
+     */
+    title: z.string().optional(),
+});
+/** `fileContent` query, beside the share parameters. */
+const fileContentQuerySchema = z.object({
+    /** `1`: send the file text without rendering it. */
+    raw: z
+        .string()
+        .optional()
+        .describe('1: return the source without rendering it.'),
+    /** `1`: render embedded diagrams into the HTML. */
+    render_diagrams: z
+        .string()
+        .optional()
+        .describe('1: render embedded diagrams into the HTML.'),
+});
+/** `fileWrite` body. */
+const fileWriteBodySchema = z.object({
+    /** New file content. */
+    content: z.string().describe('New file content'),
+});
+/** `fileWrite` response. */
+const fileWriteResponseSchema = z.object({
+    /** Always true. */
+    ok: z.literal(true),
+    /** Filesystem path written. */
+    path: z.string(),
+    /** Bytes written (UTF-8). */
+    size: z.number(),
+});
+/** `{ ok: true }`. */
+const okResponseSchema = z.object({
+    /** Always true. */
+    ok: z.literal(true),
+});
+/** One available export of a path. */
+const exportLinkSchema = z.object({
+    /** Export format (`pdf`, `docx`, `zip`, `svg`, ...). */
+    format: z.string(),
+    /** Export URL (server-relative). */
+    url: z.string(),
+});
+/** `linkInfo` response; only `exists` when the path doesn't exist. */
+const linkInfoResponseSchema = z.object({
+    /** Whether the path exists. */
+    exists: z.boolean(),
+    /** Whether it is a directory. */
+    isDirectory: z.boolean().optional(),
+    /** Page URL (server-relative). */
+    pageUrl: z.string().optional(),
+    /** Raw file URL (server-relative); null for directories. */
+    rawUrl: z.string().nullable().optional(),
+    /** Raw URL that always downloads (`?download=1`); null for directories. */
+    downloadUrl: z.string().nullable().optional(),
+    /** Available exports. */
+    exportLinks: z.array(exportLinkSchema).optional(),
+});
+/** `exportCacheClear` response. */
+const exportCacheClearResponseSchema = z.object({
+    /** Entries removed. */
+    cleared: z.object({
+        /** Cached PDF/DOCX exports removed. */
+        exports: z.number(),
+        /** Cached diagram renders removed. */
+        diagrams: z.number(),
+    }),
+});
+
+export { breadcrumbSchema, browseResponseSchema, directoryEntrySchema, directoryListingSchema, driveSchema, drivesResponseSchema, exportCacheClearResponseSchema, exportLinkSchema, fileContentQuerySchema, fileContentResponseSchema, fileMetadataSchema, fileWriteBodySchema, fileWriteResponseSchema, headingSchema, linkInfoResponseSchema, okResponseSchema };

package/dist/src/catalog/descriptions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Descriptions of jeeves-server's own (non-standard) catalog entries, keyed by entry name: one wording for OpenAPI, the SDK and the plugin's tools. Pure data.
+ *
+ * @remarks
+ * The entries behind today's plugin tools (`browse`, `linkInfo`,
+ * `fileWrite`, `fileMutate`, `exportCacheClear`, `drives`, `authStatus`,
+ * `resolvePath`) keep the tools' descriptions, so the tools read the same
+ * once they are built from the catalog.
+ *
+ * @packageDocumentation
+ */
+/** Description of each entry, keyed by entry name. */
+export declare const ENTRY_DESCRIPTIONS: {
+    readonly health: "Liveness check: returns { ok: true }, with no downstream checks.";
+    readonly authStatus: "Check current authentication status. Returns whether authenticated, email, insider status, and key metadata.";
+    readonly sendMagicLink: "Request a sign-in link by email. Always answers with a verification URL, whether or not the email belongs to an insider.";
+    readonly drives: "List available root drives/labels configured on the server.";
+    readonly browse: "Get file or directory metadata. For files: size, mtime, content type, rendered HTML availability. For directories: listing of entries.";
+    readonly fileContent: "Get a file with type-specific handling: Markdown, CSV and diagrams rendered to HTML, other text as is, images and binaries by name. `raw=1` skips rendering.";
+    readonly fileWrite: "Overwrite the content of an existing file. Insider-only; the file must already exist.";
+    readonly fileMutate: "Apply a structured mutation to a .md file. Insider-only. Supports: edit-block, delete-block, insert-block, edit-cell, toggle-checkbox.";
+    readonly raw: "Download a file as is, with its own content type. `download=1` always sends it as an attachment.";
+    readonly export: "Export a Markdown document as PDF or DOCX, or a directory as a ZIP or Tar archive (archives for insiders only).";
+    readonly exportCacheClear: "Clear the export and diagram caches for a given path.";
+    readonly exportMermaid: "Export a Mermaid diagram file as SVG, PNG or PDF.";
+    readonly exportPlantUml: "Export a PlantUML diagram file in one of the formats the configured renderers support (SVG, PNG, PDF, EPS).";
+    readonly linkInfo: "Query available link types for a path (exists, page URL, raw URL, export links for PDF/DOCX/SVG/PNG).";
+    readonly diagram: "Get a diagram embedded in a rendered document, as SVG, by its type and content hash.";
+    readonly publicContent: "Get one of the public pages of the server (readme, privacy, terms) rendered as Markdown.";
+    readonly share: "Sign a share link for a path: a path key, optionally expiring, or a deep share (`depth`, `dirs`). The response reports whether the path is a directory.";
+    readonly shareFor: "Sign a share link for a path aimed at named insiders: an insider link when every recipient is an insider with access, else an outsider share checked against the outsider policy.";
+    readonly contentLink: "Pre-computed share link for one of the pinned content pages of the server (privacy, terms).";
+    readonly readmeLink: "Pre-computed share link for the README of the server.";
+    readonly resolvePath: "Convert an absolute filesystem path to a server browse path and optional public URL.";
+    readonly rotateKey: "Rotate the key of the calling insider. The old insider key and every outsider link the insider signed stop working.";
+    readonly pathKey: "Compute the outsider path key for a path from the machine seed sent in X-API-Key.";
+    readonly insiderKey: "Compute the insider key for the machine seed sent in X-API-Key.";
+    readonly search: "Semantic search through jeeves-watcher, grouped by file and filtered to the scopes of the caller.";
+    readonly searchFacets: "Search facets from jeeves-watcher, passed through unchanged.";
+    readonly receiveEvent: "Event gateway webhook receiver: matches a JSON object against the configured event schemas and queues the matching command.";
+    readonly listEvents: "Recent event log entries, newest last (insiders with no scopes configured; limit capped at 100).";
+    readonly oauthStart: "Start an OAuth2 authorization code flow; returns the URL to open in a browser.";
+    readonly oauthStatus: "Check whether valid OAuth2 credentials exist for a provider/account.";
+    readonly oauthToken: "Get a valid access token for a provider/account, refreshing it when expired.";
+    readonly runnerListJobs: "List the jeeves-runner jobs (runner GET /jobs).";
+    readonly runnerGetJob: "One jeeves-runner job (runner GET /jobs/:id).";
+    readonly runnerListRuns: "A jeeves-runner job's recent runs (runner GET /jobs/:id/runs).";
+    readonly runnerRunJob: "Run a jeeves-runner job now (runner POST /jobs/:id/run).";
+    readonly runnerEnableJob: "Enable a jeeves-runner job (runner PATCH /jobs/:id/enable).";
+    readonly runnerDisableJob: "Disable a jeeves-runner job (runner PATCH /jobs/:id/disable).";
+    readonly runnerStatus: "jeeves-runner status (runner GET /status).";
+};

package/dist/src/catalog/descriptions.js

@@ -0,0 +1,54 @@
+/**
+ * Descriptions of jeeves-server's own (non-standard) catalog entries, keyed by entry name: one wording for OpenAPI, the SDK and the plugin's tools. Pure data.
+ *
+ * @remarks
+ * The entries behind today's plugin tools (`browse`, `linkInfo`,
+ * `fileWrite`, `fileMutate`, `exportCacheClear`, `drives`, `authStatus`,
+ * `resolvePath`) keep the tools' descriptions, so the tools read the same
+ * once they are built from the catalog.
+ *
+ * @packageDocumentation
+ */
+/** Description of each entry, keyed by entry name. */
+const ENTRY_DESCRIPTIONS = {
+    health: 'Liveness check: returns { ok: true }, with no downstream checks.',
+    authStatus: 'Check current authentication status. Returns whether authenticated, email, insider status, and key metadata.',
+    sendMagicLink: 'Request a sign-in link by email. Always answers with a verification URL, whether or not the email belongs to an insider.',
+    drives: 'List available root drives/labels configured on the server.',
+    browse: 'Get file or directory metadata. For files: size, mtime, content type, rendered HTML availability. For directories: listing of entries.',
+    fileContent: 'Get a file with type-specific handling: Markdown, CSV and diagrams rendered to HTML, other text as is, images and binaries by name. `raw=1` skips rendering.',
+    fileWrite: 'Overwrite the content of an existing file. Insider-only; the file must already exist.',
+    fileMutate: 'Apply a structured mutation to a .md file. Insider-only. Supports: edit-block, delete-block, insert-block, edit-cell, toggle-checkbox.',
+    raw: 'Download a file as is, with its own content type. `download=1` always sends it as an attachment.',
+    export: 'Export a Markdown document as PDF or DOCX, or a directory as a ZIP or Tar archive (archives for insiders only).',
+    exportCacheClear: 'Clear the export and diagram caches for a given path.',
+    exportMermaid: 'Export a Mermaid diagram file as SVG, PNG or PDF.',
+    exportPlantUml: 'Export a PlantUML diagram file in one of the formats the configured renderers support (SVG, PNG, PDF, EPS).',
+    linkInfo: 'Query available link types for a path (exists, page URL, raw URL, export links for PDF/DOCX/SVG/PNG).',
+    diagram: 'Get a diagram embedded in a rendered document, as SVG, by its type and content hash.',
+    publicContent: 'Get one of the public pages of the server (readme, privacy, terms) rendered as Markdown.',
+    share: 'Sign a share link for a path: a path key, optionally expiring, or a deep share (`depth`, `dirs`). The response reports whether the path is a directory.',
+    shareFor: 'Sign a share link for a path aimed at named insiders: an insider link when every recipient is an insider with access, else an outsider share checked against the outsider policy.',
+    contentLink: 'Pre-computed share link for one of the pinned content pages of the server (privacy, terms).',
+    readmeLink: 'Pre-computed share link for the README of the server.',
+    resolvePath: 'Convert an absolute filesystem path to a server browse path and optional public URL.',
+    rotateKey: 'Rotate the key of the calling insider. The old insider key and every outsider link the insider signed stop working.',
+    pathKey: 'Compute the outsider path key for a path from the machine seed sent in X-API-Key.',
+    insiderKey: 'Compute the insider key for the machine seed sent in X-API-Key.',
+    search: 'Semantic search through jeeves-watcher, grouped by file and filtered to the scopes of the caller.',
+    searchFacets: 'Search facets from jeeves-watcher, passed through unchanged.',
+    receiveEvent: 'Event gateway webhook receiver: matches a JSON object against the configured event schemas and queues the matching command.',
+    listEvents: 'Recent event log entries, newest last (insiders with no scopes configured; limit capped at 100).',
+    oauthStart: 'Start an OAuth2 authorization code flow; returns the URL to open in a browser.',
+    oauthStatus: 'Check whether valid OAuth2 credentials exist for a provider/account.',
+    oauthToken: 'Get a valid access token for a provider/account, refreshing it when expired.',
+    runnerListJobs: 'List the jeeves-runner jobs (runner GET /jobs).',
+    runnerGetJob: 'One jeeves-runner job (runner GET /jobs/:id).',
+    runnerListRuns: "A jeeves-runner job's recent runs (runner GET /jobs/:id/runs).",
+    runnerRunJob: 'Run a jeeves-runner job now (runner POST /jobs/:id/run).',
+    runnerEnableJob: 'Enable a jeeves-runner job (runner PATCH /jobs/:id/enable).',
+    runnerDisableJob: 'Disable a jeeves-runner job (runner PATCH /jobs/:id/disable).',
+    runnerStatus: 'jeeves-runner status (runner GET /status).',
+};
+
+export { ENTRY_DESCRIPTIONS };

package/dist/src/catalog/eventEntries.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The event entries of the server catalog: the webhook receiver (`receiveEvent`, any JSON object; Decision 14) and the event log (`listEvents`). Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** `receiveEvent` response. */
+export declare const receiveEventResponseSchema: z.ZodObject<{
+    matched: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/** One event log entry. Entries written by other versions keep their fields. */
+export declare const eventLogEntrySchema: z.ZodObject<{
+    ts: z.ZodString;
+    event: z.ZodNullable<z.ZodString>;
+    matched: z.ZodBoolean;
+    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    timedOut: z.ZodOptional<z.ZodBoolean>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    bodyPreview: z.ZodOptional<z.ZodString>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    originalBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$loose>;
+/** The event entries. */
+export declare const EVENT_ENTRIES: readonly [{
+    readonly body: z.ZodObject<{}, z.core.$loose>;
+    readonly response: z.ZodObject<{
+        matched: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "query";
+            readonly name: "k";
+        }];
+    };
+    readonly kind: "write";
+    readonly name: "receiveEvent";
+    readonly method: "POST";
+    readonly path: "/event";
+    readonly description: "Event gateway webhook receiver: matches a JSON object against the configured event schemas and queues the matching command.";
+}, {
+    readonly query: z.ZodObject<{
+        limit: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    readonly response: z.ZodArray<z.ZodObject<{
+        ts: z.ZodString;
+        event: z.ZodNullable<z.ZodString>;
+        matched: z.ZodBoolean;
+        exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        timedOut: z.ZodOptional<z.ZodBoolean>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        bodyPreview: z.ZodOptional<z.ZodString>;
+        truncated: z.ZodOptional<z.ZodBoolean>;
+        originalBytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "query";
+            readonly name: "k";
+        }, {
+            readonly in: "cookie";
+            readonly name: "jeeves_session";
+        }];
+        readonly insiderOnly: true;
+    };
+    readonly kind: "read";
+    readonly name: "listEvents";
+    readonly method: "GET";
+    readonly path: "/api/events";
+    readonly description: "Recent event log entries, newest last (insiders with no scopes configured; limit capped at 100).";
+}];

package/dist/src/catalog/eventEntries.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { EVENT_KEY, INSIDER_ONLY, route } from './route.js';
+
+/**
+ * The event entries of the server catalog: the webhook receiver (`receiveEvent`, any JSON object; Decision 14) and the event log (`listEvents`). Pure.
+ *
+ * @packageDocumentation
+ */
+/** `receiveEvent` response. */
+const receiveEventResponseSchema = z.object({
+    /** Name of the event that matched, or null (the body is logged). */
+    matched: z.string().nullable(),
+});
+/** One event log entry. Entries written by other versions keep their fields. */
+const eventLogEntrySchema = z.looseObject({
+    /** When it was logged (ISO). */
+    ts: z.string(),
+    /** Matched event name, or null for an unmatched body. */
+    event: z.string().nullable(),
+    /** Whether the body matched an event. */
+    matched: z.boolean(),
+    /** Exit code of the event command; null when it was killed by a signal. */
+    exitCode: z.number().nullable().optional(),
+    /** True when the command timed out (it and its process tree were killed). */
+    timedOut: z.boolean().optional(),
+    /** Command duration. */
+    durationMs: z.number().optional(),
+    /** Unmatched body as JSON, capped at 256 KiB. */
+    bodyPreview: z.string().optional(),
+    /** True when `bodyPreview` was cut at the cap. */
+    truncated: z.boolean().optional(),
+    /** UTF-8 byte length of the full body, when truncated. */
+    originalBytes: z.number().optional(),
+});
+/** The event entries. */
+const EVENT_ENTRIES = [
+    {
+        ...route('receiveEvent', 'POST', '/event'),
+        body: z.looseObject({}),
+        response: receiveEventResponseSchema,
+        auth: EVENT_KEY,
+        kind: 'write',
+    },
+    {
+        ...route('listEvents', 'GET', '/api/events'),
+        query: z.object({
+            // A string, as today: a value that isn't a number gives the default.
+            limit: z
+                .string()
+                .optional()
+                .describe('Entries to return (default 20, at most 100).'),
+        }),
+        response: z.array(eventLogEntrySchema),
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+];
+
+export { EVENT_ENTRIES, eventLogEntrySchema, receiveEventResponseSchema };

package/dist/src/catalog/fileMutateSchema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `fileMutate` request body: one object with an `action` enum and the union of the actions' fields, each action's required fields checked by a refinement (catalog bodies must be Zod objects). Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** The mutation actions. */
+export declare const FILE_MUTATION_ACTIONS: readonly ["edit-block", "delete-block", "insert-block", "edit-cell", "toggle-checkbox"];
+/** Fields each action requires. */
+export declare const FILE_MUTATION_REQUIRED_FIELDS: {
+    readonly 'edit-block': readonly ["startLine", "endLine", "content"];
+    readonly 'delete-block': readonly ["startLine", "endLine"];
+    readonly 'insert-block': readonly ["atLine", "position", "content"];
+    readonly 'edit-cell': readonly ["line", "col", "content"];
+    readonly 'toggle-checkbox': readonly ["index", "checked"];
+};
+/** `fileMutate` body. */
+export declare const fileMutateBodySchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        "edit-block": "edit-block";
+        "delete-block": "delete-block";
+        "insert-block": "insert-block";
+        "edit-cell": "edit-cell";
+        "toggle-checkbox": "toggle-checkbox";
+    }>;
+    startLine: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    content: z.ZodOptional<z.ZodString>;
+    atLine: z.ZodOptional<z.ZodNumber>;
+    position: z.ZodOptional<z.ZodEnum<{
+        before: "before";
+        after: "after";
+    }>>;
+    context: z.ZodOptional<z.ZodString>;
+    line: z.ZodOptional<z.ZodNumber>;
+    col: z.ZodOptional<z.ZodNumber>;
+    index: z.ZodOptional<z.ZodNumber>;
+    checked: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** A parsed `fileMutate` body. */
+export type FileMutateBody = z.infer<typeof fileMutateBodySchema>;