@karmaniverous/jeeves-server-core 0.4.0 → 0.5.0

package/dist/src/catalog/serverCatalog.js

@@ -0,0 +1,37 @@
+import { defineCatalog, standardEntries } from '@karmaniverous/jeeves/catalog';
+import { CONTENT_ENTRIES } from './contentEntries.js';
+import { EVENT_ENTRIES } from './eventEntries.js';
+import { OAUTH_ENTRIES } from './oauthEntries.js';
+import { INSIDER_ONLY } from './route.js';
+import { RUNNER_ENTRIES } from './runnerEntries.js';
+import { SHARING_ENTRIES } from './sharingEntries.js';
+import { serverHealthSchema } from './statusSchemas.js';
+import { UTILITY_ENTRIES } from './utilityEntries.js';
+
+/**
+ * The jeeves-server endpoint catalog (`SERVER_CATALOG`): one Zod-described entry per machine-API route, from which the service's routes and validation, the OpenAPI document, the SDK client and the plugin's tools are derived; plus the types inferred from it. Pure.
+ *
+ * @remarks
+ * jeeves' three standard entries (`status` public; `config` and
+ * `configApply` admin), then the content, sharing, utility, event, OAuth and
+ * runner entries. Entry names are the SDK method, the plugin tool's base
+ * name (`server_` + snake_case) and the OpenAPI `operationId`. Browser
+ * routes (the SPA, sign-in, `/oauth/callback`, `/go/:slug`) are not in it.
+ *
+ * @packageDocumentation
+ */
+/** The jeeves-server endpoint catalog. */
+const SERVER_CATALOG = defineCatalog([
+    ...standardEntries('server', {
+        auth: { config: INSIDER_ONLY },
+        healthSchema: serverHealthSchema,
+    }),
+    ...UTILITY_ENTRIES,
+    ...CONTENT_ENTRIES,
+    ...SHARING_ENTRIES,
+    ...EVENT_ENTRIES,
+    ...OAUTH_ENTRIES,
+    ...RUNNER_ENTRIES,
+]);
+
+export { SERVER_CATALOG };

package/dist/src/catalog/serverCatalog.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * `SERVER_CATALOG` (next-api-catalog.md, Entry inventory): every entry with its method, path, kind and access class, complete descriptions and schemas, the tool names the plugin keeps, the share parameters on content and navigation entries, and the binary entries' content types.
+ */
+export {};

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

@@ -0,0 +1,200 @@
+/**
+ * The sharing entries of the server catalog: share, shareFor, contentLink, readmeLink, resolvePath and rotateKey, with their request and response schemas. Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** `share` body. */
+export declare const shareBodySchema: z.ZodObject<{
+    path: z.ZodString;
+    expiry: z.ZodOptional<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    dirs: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** `share` response. */
+export declare const shareResponseSchema: z.ZodObject<{
+    url: z.ZodString;
+    path: z.ZodString;
+    exp: z.ZodNullable<z.ZodString>;
+    depth: z.ZodNumber;
+    dirs: z.ZodBoolean;
+    isDirectory: z.ZodBoolean;
+}, z.core.$strip>;
+/** `shareFor` body. */
+export declare const shareForBodySchema: z.ZodObject<{
+    path: z.ZodString;
+    insiders: z.ZodArray<z.ZodString>;
+    depth: z.ZodOptional<z.ZodNumber>;
+    dirs: z.ZodOptional<z.ZodBoolean>;
+    enforceOutsiderPolicy: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** `shareFor` response. */
+export declare const shareForResponseSchema: z.ZodObject<{
+    url: z.ZodNullable<z.ZodString>;
+    type: z.ZodEnum<{
+        insider: "insider";
+        "outsider-share": "outsider-share";
+        blocked: "blocked";
+        "policy-denied": "policy-denied";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+    blocked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    warning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `{ url }`: a pre-computed share link. */
+export declare const linkResponseSchema: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strip>;
+/** `resolvePath` response. */
+export declare const resolvePathResponseSchema: z.ZodObject<{
+    browsePath: z.ZodString;
+    browseUrl: z.ZodString;
+    publicUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** `rotateKey` response. */
+export declare const rotateKeyResponseSchema: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    keyCreatedAt: z.ZodString;
+    invalidates: z.ZodArray<z.ZodEnum<{
+        insiderKey: "insiderKey";
+        outsiderLinks: "outsiderLinks";
+    }>>;
+}, z.core.$strip>;
+/** The sharing entries. */
+export declare const SHARING_ENTRIES: readonly [{
+    readonly body: z.ZodObject<{
+        path: z.ZodString;
+        expiry: z.ZodOptional<z.ZodString>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        dirs: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        url: z.ZodString;
+        path: z.ZodString;
+        exp: z.ZodNullable<z.ZodString>;
+        depth: z.ZodNumber;
+        dirs: z.ZodBoolean;
+        isDirectory: z.ZodBoolean;
+    }, z.core.$strip>;
+    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: "share";
+    readonly method: "POST";
+    readonly path: "/api/share";
+    readonly description: "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 body: z.ZodObject<{
+        path: z.ZodString;
+        insiders: z.ZodArray<z.ZodString>;
+        depth: z.ZodOptional<z.ZodNumber>;
+        dirs: z.ZodOptional<z.ZodBoolean>;
+        enforceOutsiderPolicy: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        url: z.ZodNullable<z.ZodString>;
+        type: z.ZodEnum<{
+            insider: "insider";
+            "outsider-share": "outsider-share";
+            blocked: "blocked";
+            "policy-denied": "policy-denied";
+        }>;
+        reason: z.ZodOptional<z.ZodString>;
+        blocked: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        warning: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    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: "shareFor";
+    readonly method: "POST";
+    readonly path: "/api/util/share-for";
+    readonly description: "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 params: z.ZodObject<{
+        file: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>;
+    readonly auth: "none";
+    readonly kind: "read";
+    readonly name: "contentLink";
+    readonly method: "GET";
+    readonly path: "/api/content-link/:file";
+    readonly description: "Pre-computed share link for one of the pinned content pages of the server (privacy, terms).";
+}, {
+    readonly response: z.ZodObject<{
+        url: z.ZodString;
+    }, z.core.$strip>;
+    readonly auth: "none";
+    readonly kind: "read";
+    readonly name: "readmeLink";
+    readonly method: "GET";
+    readonly path: "/api/readme-link";
+    readonly description: "Pre-computed share link for the README of the server.";
+}, {
+    readonly query: z.ZodObject<{
+        fsPath: z.ZodString;
+    }, z.core.$strip>;
+    readonly response: z.ZodObject<{
+        browsePath: z.ZodString;
+        browseUrl: z.ZodString;
+        publicUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    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: "resolvePath";
+    readonly method: "GET";
+    readonly path: "/api/resolve-path";
+    readonly description: "Convert an absolute filesystem path to a server browse path and optional public URL.";
+}, {
+    readonly response: z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        keyCreatedAt: z.ZodString;
+        invalidates: z.ZodArray<z.ZodEnum<{
+            insiderKey: "insiderKey";
+            outsiderLinks: "outsiderLinks";
+        }>>;
+    }, z.core.$strip>;
+    readonly auth: {
+        readonly schemes: readonly [{
+            readonly in: "query";
+            readonly name: "k";
+        }, {
+            readonly in: "cookie";
+            readonly name: "jeeves_session";
+        }];
+        readonly insiderOnly: true;
+    };
+    readonly kind: "destructive";
+    readonly name: "rotateKey";
+    readonly method: "POST";
+    readonly path: "/api/rotate-key";
+    readonly description: "Rotate the key of the calling insider. The old insider key and every outsider link the insider signed stop working.";
+}];

package/dist/src/catalog/sharingEntries.js

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+import { INSIDER_ONLY, PUBLIC, route } from './route.js';
+
+/**
+ * The sharing entries of the server catalog: share, shareFor, contentLink, readmeLink, resolvePath and rotateKey, with their request and response schemas. Pure.
+ *
+ * @packageDocumentation
+ */
+/** `share` body. */
+const shareBodySchema = z.object({
+    /** Path to share (`/<root>/<path>`). */
+    path: z.string().describe('Path to share (/<root>/<path>).'),
+    /** Expiry (Unix ms, as a string); omit for a link that doesn't expire. */
+    expiry: z
+        .string()
+        .optional()
+        .describe('Expiry (Unix milliseconds); omit for no expiry.'),
+    /** Deep share depth (levels of links the recipient may follow). */
+    depth: z.number().int().optional().describe('Deep share depth.'),
+    /** Deep share: directories below the path may be listed. */
+    dirs: z
+        .boolean()
+        .optional()
+        .describe('Deep share: directories below the path may be opened.'),
+});
+/** `share` response. */
+const shareResponseSchema = z.object({
+    /** Share URL (server-relative). */
+    url: z.string(),
+    /** The shared path. */
+    path: z.string(),
+    /** Expiry as given, or null. */
+    exp: z.string().nullable(),
+    /** Deep share depth (0 for a path share). */
+    depth: z.number(),
+    /** Deep share `dirs`. */
+    dirs: z.boolean(),
+    /** Whether the path is a directory. */
+    isDirectory: z.boolean(),
+});
+/** `shareFor` body. */
+const shareForBodySchema = z.object({
+    /** Path to share (`/<root>/<path>`). */
+    path: z.string().describe('Path to share (/<root>/<path>).'),
+    /** Recipients: insider emails, or anyone else (an outsider). */
+    insiders: z
+        .array(z.string())
+        .describe('Recipients: insider emails; anyone else is an outsider.'),
+    /** Deep share depth. */
+    depth: z.number().int().optional().describe('Deep share depth.'),
+    /** Deep share `dirs`. */
+    dirs: z
+        .boolean()
+        .optional()
+        .describe('Deep share: directories below the path may be opened.'),
+    /** `false`: sign even where the outsider policy denies (with a warning). */
+    enforceOutsiderPolicy: z
+        .boolean()
+        .optional()
+        .describe('false: sign even where the outsider policy denies.'),
+});
+/** `shareFor` response. */
+const shareForResponseSchema = z.object({
+    /** The link (absolute when a public URL is configured), or null. */
+    url: z.string().nullable(),
+    /** What was produced. */
+    type: z.enum(['insider', 'outsider-share', 'blocked', 'policy-denied']),
+    /** Why no link was produced. */
+    reason: z.string().optional(),
+    /** Recipients without access to the path (`blocked`). */
+    blocked: z.array(z.string()).optional(),
+    /** Set when the outsider policy would have denied the link. */
+    warning: z.string().optional(),
+});
+/** `{ url }`: a pre-computed share link. */
+const linkResponseSchema = z.object({
+    /** Share URL (server-relative). */
+    url: z.string(),
+});
+/** `resolvePath` response. */
+const resolvePathResponseSchema = z.object({
+    /** Browse path (`<root>/<path>`). */
+    browsePath: z.string(),
+    /** Page URL (server-relative, encoded). */
+    browseUrl: z.string(),
+    /** Absolute page URL, when a public URL is configured. */
+    publicUrl: z.string().optional(),
+});
+/** `rotateKey` response. */
+const rotateKeyResponseSchema = z.object({
+    /** Always true. */
+    ok: z.literal(true),
+    /** When the new key was created (ISO). */
+    keyCreatedAt: z.string(),
+    /** What stopped working: the insider key and the insider's outsider links. */
+    invalidates: z.array(z.enum(['insiderKey', 'outsiderLinks'])),
+});
+/** The sharing entries. */
+const SHARING_ENTRIES = [
+    {
+        ...route('share', 'POST', '/api/share'),
+        body: shareBodySchema,
+        response: shareResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+    {
+        ...route('shareFor', 'POST', '/api/util/share-for'),
+        body: shareForBodySchema,
+        response: shareForResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+    {
+        ...route('contentLink', 'GET', '/api/content-link/:file'),
+        params: z.object({
+            file: z.string().describe('Content page: privacy or terms.'),
+        }),
+        response: linkResponseSchema,
+        auth: PUBLIC,
+        kind: 'read',
+    },
+    {
+        ...route('readmeLink', 'GET', '/api/readme-link'),
+        response: linkResponseSchema,
+        auth: PUBLIC,
+        kind: 'read',
+    },
+    {
+        ...route('resolvePath', 'GET', '/api/resolve-path'),
+        query: z.object({
+            fsPath: z.string().describe('Absolute filesystem path to resolve'),
+        }),
+        response: resolvePathResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'read',
+    },
+    {
+        ...route('rotateKey', 'POST', '/api/rotate-key'),
+        response: rotateKeyResponseSchema,
+        auth: INSIDER_ONLY,
+        kind: 'destructive',
+    },
+];
+
+export { SHARING_ENTRIES, linkResponseSchema, resolvePathResponseSchema, rotateKeyResponseSchema, shareBodySchema, shareForBodySchema, shareForResponseSchema, shareResponseSchema };

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

@@ -0,0 +1,87 @@
+/**
+ * The server's `health` block in `GET /status` (`serverHealthSchema`): today's block plus the 3.16.0 additions (sign-in redirect URIs, `eventQueue`), with the event commands and the Chrome path optional because callers that aren't admin don't get them (Decision 22). Pure.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/** A downstream service as `/status` last saw it. */
+export declare const serviceProbeSchema: z.ZodObject<{
+    url: z.ZodString;
+    reachable: z.ZodBoolean;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Event queue progress (counts since start; timestamps ISO). */
+export declare const eventQueueHealthSchema: z.ZodObject<{
+    offset: z.ZodNumber;
+    size: z.ZodNumber;
+    pendingBytes: z.ZodNumber;
+    parseErrors: z.ZodNumber;
+    lastCursorReset: z.ZodOptional<z.ZodString>;
+    lastRewind: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The server's `health` details. */
+export declare const serverHealthSchema: z.ZodObject<{
+    port: z.ZodNumber;
+    chrome: z.ZodObject<{
+        configured: z.ZodBoolean;
+        path: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    auth: z.ZodObject<{
+        modes: z.ZodArray<z.ZodString>;
+        insiderCount: z.ZodNumber;
+        keyCount: z.ZodNumber;
+        googleRedirectUri: z.ZodOptional<z.ZodString>;
+        oauthRedirectUri: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    events: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        cmd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    eventQueue: z.ZodObject<{
+        offset: z.ZodNumber;
+        size: z.ZodNumber;
+        pendingBytes: z.ZodNumber;
+        parseErrors: z.ZodNumber;
+        lastCursorReset: z.ZodOptional<z.ZodString>;
+        lastRewind: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    exports: z.ZodObject<{
+        documents: z.ZodArray<z.ZodString>;
+        directories: z.ZodArray<z.ZodString>;
+        diagrams: z.ZodArray<z.ZodString>;
+        chromeAvailable: z.ZodBoolean;
+    }, z.core.$strip>;
+    diagrams: z.ZodObject<{
+        mermaid: z.ZodBoolean;
+        plantuml: z.ZodObject<{
+            localJar: z.ZodBoolean;
+            servers: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    services: z.ZodObject<{
+        watcher: z.ZodObject<{
+            url: z.ZodString;
+            reachable: z.ZodBoolean;
+            version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        runner: z.ZodObject<{
+            url: z.ZodString;
+            reachable: z.ZodBoolean;
+            version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        meta: z.ZodObject<{
+            url: z.ZodString;
+            reachable: z.ZodBoolean;
+            version: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        lastChecked: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    branding: z.ZodObject<{
+        name: z.ZodString;
+        emoji: z.ZodOptional<z.ZodString>;
+        theme: z.ZodOptional<z.ZodObject<{
+            light: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            dark: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;

package/dist/src/catalog/statusSchemas.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+
+/**
+ * The server's `health` block in `GET /status` (`serverHealthSchema`): today's block plus the 3.16.0 additions (sign-in redirect URIs, `eventQueue`), with the event commands and the Chrome path optional because callers that aren't admin don't get them (Decision 22). Pure.
+ *
+ * @packageDocumentation
+ */
+/** CSS variable overrides of one theme mode. */
+const cssOverridesSchema = z.record(z.string(), z.string());
+/** A downstream service as `/status` last saw it. */
+const serviceProbeSchema = z.object({
+    /** Service URL. */
+    url: z.string(),
+    /** Whether its `/status` or `/health` answered. */
+    reachable: z.boolean(),
+    /** Version it reported. */
+    version: z.string().optional(),
+});
+/** Event queue progress (counts since start; timestamps ISO). */
+const eventQueueHealthSchema = z.object({
+    /** Byte offset the processor has reached. */
+    offset: z.number(),
+    /** Queue file size in bytes. */
+    size: z.number(),
+    /** Bytes not yet processed. */
+    pendingBytes: z.number(),
+    /** Queue lines that could not be parsed. */
+    parseErrors: z.number(),
+    /** Last time the cursor was reset. */
+    lastCursorReset: z.string().optional(),
+    /** Last time the processor rewound. */
+    lastRewind: z.string().optional(),
+});
+/** The server's `health` details. */
+const serverHealthSchema = z.object({
+    /** Listening port. */
+    port: z.number(),
+    /** Chrome (PDF and diagram rendering). */
+    chrome: z.object({
+        /** Whether a Chrome path is configured. */
+        configured: z.boolean(),
+        /** Configured Chrome path (admin callers only). */
+        path: z.string().optional(),
+    }),
+    /** Sign-in configuration. */
+    auth: z.object({
+        /** Enabled sign-in modes. */
+        modes: z.array(z.string()),
+        /** Configured insiders. */
+        insiderCount: z.number(),
+        /** Configured machine keys. */
+        keyCount: z.number(),
+        /** Google sign-in redirect URI (google mode with a public origin). */
+        googleRedirectUri: z.string().optional(),
+        /** OAuth provider redirect URI (when providers are configured). */
+        oauthRedirectUri: z.string().optional(),
+    }),
+    /** Configured webhook events. */
+    events: z.array(z.object({
+        /** Event name. */
+        name: z.string(),
+        /** Command it runs (admin callers only). */
+        cmd: z.string().optional(),
+    })),
+    /** Event queue progress. */
+    eventQueue: eventQueueHealthSchema,
+    /** Export capabilities. */
+    exports: z.object({
+        /** Document formats. */
+        documents: z.array(z.string()),
+        /** Directory archive formats. */
+        directories: z.array(z.string()),
+        /** Diagram formats. */
+        diagrams: z.array(z.string()),
+        /** Whether Chrome is configured. */
+        chromeAvailable: z.boolean(),
+    }),
+    /** Diagram rendering. */
+    diagrams: z.object({
+        /** Mermaid is available. */
+        mermaid: z.boolean(),
+        /** PlantUML renderers. */
+        plantuml: z.object({
+            /** A local PlantUML jar is configured. */
+            localJar: z.boolean(),
+            /** PlantUML servers. */
+            servers: z.array(z.string()),
+        }),
+    }),
+    /** Downstream Jeeves services (probed in the background). */
+    services: z.object({
+        /** jeeves-watcher. */
+        watcher: serviceProbeSchema,
+        /** jeeves-runner. */
+        runner: serviceProbeSchema,
+        /** jeeves-meta. */
+        meta: serviceProbeSchema,
+        /** Last probe (ISO), or null before the first. */
+        lastChecked: z.string().nullable(),
+    }),
+    /** Branding. */
+    branding: z.object({
+        /** Product name. */
+        name: z.string(),
+        /** Emoji. */
+        emoji: z.string().optional(),
+        /** CSS variable overrides per theme mode. */
+        theme: z
+            .object({
+            /** Light mode overrides. */
+            light: cssOverridesSchema.optional(),
+            /** Dark mode overrides. */
+            dark: cssOverridesSchema.optional(),
+        })
+            .optional(),
+    }),
+});
+
+export { eventQueueHealthSchema, serverHealthSchema, serviceProbeSchema };