@karmaniverous/jeeves-server-core 0.1.3 → 0.1.5

package/README.md

@@ -14,6 +14,21 @@ Shared workspace package providing cryptographic utilities and API types consume
 | `computeDeepShareKey(seed, path, params)` | HMAC-SHA256 key for deep directory shares with depth/dirs/stack/expiry |
 | `timingSafeEqual(a, b)` | Constant-time string comparison to prevent timing attacks |
 
+### Config Schema
+
+| Export | Description |
+|--------|-------------|
+| `loggingConfigSchema` | Zod schema for `logging` config block (`level`, `file`, both optional) |
+| `LoggingConfig` | Inferred TypeScript type from `loggingConfigSchema` |
+| `jeevesConfigSchema` | Full server config Zod schema (includes `logging`, `oauth`, all other fields) |
+
+### Endpoint Catalog
+
+| Export | Description |
+|--------|-------------|
+| `EndpointEntry` | Interface describing a single API operation (method, path, description, auth flags) |
+| `serverEndpoints` | Complete declarative catalog of all jeeves-server API endpoints (38 entries) |
+
 ### API Types
 
 | Type | Description |
@@ -36,6 +51,9 @@ Shared workspace package providing cryptographic utilities and API types consume
 import {
   computeInsiderKey,
   computePathKey,
+  serverEndpoints,
+  type EndpointEntry,
+  type LoggingConfig,
   type ShareRequest,
 } from '@karmaniverous/jeeves-server-core';
 ```

package/dist/src/endpoints.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Declarative endpoint catalog — single source of truth for the jeeves-server
+ * API surface. Consumers (CLI, OpenClaw plugin) derive their registrations
+ * from this catalog.
+ *
+ * @packageDocumentation
+ */
+import type { z } from 'zod';
+/**
+ * Describes a single API operation.
+ */
+export interface EndpointEntry {
+    /** HTTP method. */
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** URL path pattern (Fastify-style, e.g. '/api/file/*'). */
+    path: string;
+    /** Human-readable operation description. */
+    description: string;
+    /** Zod schema for query params (GET) or request body (POST/PUT). */
+    params?: z.ZodType;
+    /** Zod schema for the response body. */
+    response?: z.ZodType;
+    /** Whether the endpoint requires insider auth. */
+    insiderOnly?: boolean;
+    /** Whether the endpoint is unauthenticated. */
+    unauthenticated?: boolean;
+}
+/**
+ * Complete API endpoint catalog for jeeves-server.
+ *
+ * Keys are stable operation identifiers used by consumers to reference
+ * specific endpoints. Values describe the HTTP operation.
+ */
+export declare const serverEndpoints: Record<string, EndpointEntry>;

package/dist/src/endpoints.js

@@ -0,0 +1,235 @@
+/**
+ * Declarative endpoint catalog — single source of truth for the jeeves-server
+ * API surface. Consumers (CLI, OpenClaw plugin) derive their registrations
+ * from this catalog.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Complete API endpoint catalog for jeeves-server.
+ *
+ * Keys are stable operation identifiers used by consumers to reference
+ * specific endpoints. Values describe the HTTP operation.
+ */
+const serverEndpoints = {
+    // --- Status & Config ---
+    status: {
+        method: 'GET',
+        path: '/status',
+        description: 'Server health: name, version, uptime, status, health details.',
+        unauthenticated: true,
+    },
+    config: {
+        method: 'GET',
+        path: '/config',
+        description: 'Query running config with optional JSONPath filter (?path=).',
+        unauthenticated: true,
+    },
+    'config-apply': {
+        method: 'POST',
+        path: '/config/apply',
+        description: 'Push config patch to running service (deep-merge + validate + reload).',
+        insiderOnly: true,
+    },
+    // --- Authentication ---
+    'auth-status': {
+        method: 'GET',
+        path: '/api/auth/status',
+        description: 'Check current authentication status (no auth required).',
+        unauthenticated: true,
+    },
+    'auth-login': {
+        method: 'GET',
+        path: '/auth/login',
+        description: 'Redirect to Google OAuth consent screen.',
+        unauthenticated: true,
+    },
+    'auth-callback': {
+        method: 'GET',
+        path: '/auth/callback',
+        description: 'Handle Google OAuth callback, set session cookie.',
+        unauthenticated: true,
+    },
+    'auth-logout': {
+        method: 'GET',
+        path: '/auth/logout',
+        description: 'Clear session cookie.',
+        unauthenticated: true,
+    },
+    // --- File Browser ---
+    drives: {
+        method: 'GET',
+        path: '/api/drives',
+        description: 'List available root drives/labels configured on the server.',
+    },
+    path: {
+        method: 'GET',
+        path: '/api/path/*',
+        description: 'Get directory listing for a path.',
+    },
+    'file-get': {
+        method: 'GET',
+        path: '/api/file/*',
+        description: 'Get file content with type-specific handling (markdown, csv, diagrams, etc.).',
+    },
+    'file-put': {
+        method: 'PUT',
+        path: '/api/file/*',
+        description: 'Overwrite file content (insider-only; file must already exist).',
+        insiderOnly: true,
+    },
+    'file-mutate': {
+        method: 'POST',
+        path: '/api/file/*',
+        description: 'Apply structured .md mutations: edit-block, delete-block, insert-block, edit-cell, toggle-checkbox.',
+        insiderOnly: true,
+    },
+    raw: {
+        method: 'GET',
+        path: '/api/raw/*',
+        description: 'Direct file download with appropriate content type.',
+    },
+    // --- Export ---
+    export: {
+        method: 'GET',
+        path: '/api/export/*',
+        description: 'Trigger export (PDF, DOCX, ZIP) and return download.',
+    },
+    'export-cache-clear': {
+        method: 'DELETE',
+        path: '/api/export-cache/*',
+        description: 'Clear export and diagram caches for a given path.',
+        insiderOnly: true,
+    },
+    'mermaid-export': {
+        method: 'GET',
+        path: '/api/mermaid-export/*',
+        description: 'Export Mermaid diagram (svg, png, pdf).',
+    },
+    'plantuml-export': {
+        method: 'GET',
+        path: '/api/plantuml-export/*',
+        description: 'Export PlantUML diagram (svg, png, pdf, eps).',
+    },
+    // --- Diagrams ---
+    diagram: {
+        method: 'GET',
+        path: '/api/diagram/:type/:hash',
+        description: 'Fetch rendered diagram by type and content hash.',
+        unauthenticated: true,
+    },
+    // --- Sharing ---
+    share: {
+        method: 'POST',
+        path: '/api/share',
+        description: 'Generate HMAC-signed share link for a path.',
+        insiderOnly: true,
+    },
+    'share-for': {
+        method: 'POST',
+        path: '/api/util/share-for',
+        description: 'Generate share link targeting specific insiders with configurable expiry/depth.',
+        insiderOnly: true,
+    },
+    'readme-link': {
+        method: 'GET',
+        path: '/api/readme-link',
+        description: 'Pre-computed share link for the first README.md in the directory hierarchy.',
+        unauthenticated: true,
+    },
+    'content-link': {
+        method: 'GET',
+        path: '/api/content-link/:file',
+        description: 'Pre-computed deep share URL for pinned content files (privacy, terms).',
+        unauthenticated: true,
+    },
+    'link-info': {
+        method: 'GET',
+        path: '/api/link-info/*',
+        description: 'Query available link types for a path (page, raw, PDF, DOCX, etc.).',
+    },
+    'rotate-key': {
+        method: 'POST',
+        path: '/api/rotate-key',
+        description: 'Rotate the authenticated insider API key (invalidates all existing share links).',
+        insiderOnly: true,
+    },
+    // --- Events ---
+    event: {
+        method: 'POST',
+        path: '/event',
+        description: 'Event gateway webhook receiver (scoped key auth).',
+    },
+    events: {
+        method: 'GET',
+        path: '/api/events',
+        description: 'Query recent event log entries (limit capped at 100).',
+    },
+    // --- Search ---
+    search: {
+        method: 'POST',
+        path: '/api/search',
+        description: 'Semantic search (proxied to watcher).',
+    },
+    'search-facets': {
+        method: 'GET',
+        path: '/api/search/facets',
+        description: 'Search facet metadata (proxied to watcher).',
+    },
+    // --- Runner ---
+    runner: {
+        method: 'GET',
+        path: '/api/runner/*',
+        description: 'Runner API proxy (proxied to jeeves-runner).',
+    },
+    // --- OAuth ---
+    'oauth-start': {
+        method: 'POST',
+        path: '/api/oauth/start',
+        description: 'Initiate OAuth2 authorization code flow.',
+        insiderOnly: true,
+    },
+    'oauth-status': {
+        method: 'GET',
+        path: '/api/oauth/status',
+        description: 'Check if valid OAuth2 credentials exist for a provider/account.',
+        insiderOnly: true,
+    },
+    'oauth-token': {
+        method: 'GET',
+        path: '/api/oauth/token',
+        description: 'Retrieve valid access token (with lazy refresh).',
+        insiderOnly: true,
+    },
+    'oauth-callback': {
+        method: 'GET',
+        path: '/oauth/callback',
+        description: 'OAuth2 callback (browser redirect target, unauthenticated).',
+        unauthenticated: true,
+    },
+    // --- Keys ---
+    'insider-key': {
+        method: 'GET',
+        path: '/insider-key',
+        description: 'Get insider key for the authenticated user.',
+    },
+    key: {
+        method: 'GET',
+        path: '/key',
+        description: 'Compute path-specific key.',
+    },
+    'share-legacy': {
+        method: 'GET',
+        path: '/share',
+        description: 'Generate outsider share link (top-level legacy route).',
+    },
+    // --- Shortlinks ---
+    go: {
+        method: 'GET',
+        path: '/go/:slug',
+        description: 'Shortlink redirect (unauthenticated).',
+        unauthenticated: true,
+    },
+};
+
+export { serverEndpoints };

package/dist/src/endpoints.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index.d.ts

@@ -4,5 +4,6 @@
  * @packageDocumentation
  */
 export { computeDeepShareKey, computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, type DeepShareParams, timingSafeEqual, } from './crypto.js';
-export { type AuthMode, authModeSchema, authSchema, DEPRECATED_CONFIG_PROPS, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, type JeevesConfig, jeevesConfigSchema, keyEntrySchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema, } from './schema.js';
+export { type EndpointEntry, serverEndpoints } from './endpoints.js';
+export { type AuthMode, authModeSchema, authSchema, DEPRECATED_CONFIG_PROPS, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, type JeevesConfig, jeevesConfigSchema, keyEntrySchema, type LoggingConfig, loggingConfigSchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema, } from './schema.js';
 export type { AuthStatusResponse, DriveEntry, ExportCacheClearResponse, ExportLink, FileMutationAction, LinkInfoResponse, OAuthStartRequest, OAuthStartResponse, RotateKeyResponse, ShareForRequest, ShareForResponse, ShareRequest, ShareResponse, } from './types.js';

package/dist/src/index.js

@@ -1,2 +1,3 @@
 export { computeDeepShareKey, computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, timingSafeEqual } from './crypto.js';
-export { DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema } from './schema.js';
+export { serverEndpoints } from './endpoints.js';
+export { DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, loggingConfigSchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema } from './schema.js';

package/dist/src/schema.d.ts

@@ -3,8 +3,8 @@ import { z } from 'zod';
 export declare const DEPRECATED_CONFIG_PROPS: readonly ["host", "runnerUrl", "watcherUrl", "metaUrl"];
 /** Supported authentication methods */
 export declare const authModeSchema: z.ZodEnum<{
-    google: "google";
     keys: "keys";
+    google: "google";
 }>;
 /** Google OAuth configuration */
 export declare const googleAuthSchema: z.ZodObject<{
@@ -14,8 +14,8 @@ export declare const googleAuthSchema: z.ZodObject<{
 /** Auth configuration */
 export declare const authSchema: z.ZodObject<{
     modes: z.ZodArray<z.ZodEnum<{
-        google: "google";
         keys: "keys";
+        google: "google";
     }>>;
     google: z.ZodOptional<z.ZodObject<{
         clientId: z.ZodString;
@@ -75,6 +75,13 @@ export declare const keyEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodObje
 }, z.core.$strip>]>;
 /** Check if a string is a named scope identifier (not a path glob). */
 export declare function isScopeName(v: string): boolean;
+/** Logging configuration. Not hot-reloadable — changes require service restart. */
+export declare const loggingConfigSchema: z.ZodObject<{
+    level: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** Inferred logging config type. */
+export type LoggingConfig = z.infer<typeof loggingConfigSchema>;
 /** OAuth provider configuration */
 export declare const oauthProviderSchema: z.ZodObject<{
     authUrl: z.ZodPipe<z.ZodString, z.ZodURL>;
@@ -98,8 +105,8 @@ export declare const jeevesConfigSchema: z.ZodObject<{
     chromePath: z.ZodString;
     auth: z.ZodObject<{
         modes: z.ZodArray<z.ZodEnum<{
-            google: "google";
             keys: "keys";
+            google: "google";
         }>>;
         google: z.ZodOptional<z.ZodObject<{
             clientId: z.ZodString;
@@ -151,6 +158,10 @@ export declare const jeevesConfigSchema: z.ZodObject<{
         allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
         deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>]>>;
+    logging: z.ZodOptional<z.ZodObject<{
+        level: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
     oauth: z.ZodOptional<z.ZodObject<{
         credentialDir: z.ZodString;
         providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{

package/dist/src/schema.js

@@ -101,6 +101,19 @@ function getScopeRefs(scopes) {
     }
     return [];
 }
+/** Logging configuration. Not hot-reloadable — changes require service restart. */
+const loggingConfigSchema = z.object({
+    /** Log level. */
+    level: z
+        .string()
+        .optional()
+        .describe('Logging level (trace, debug, info, warn, error, fatal).'),
+    /** Log file path. */
+    file: z
+        .string()
+        .optional()
+        .describe('Path to log file (logs to stdout if omitted).'),
+});
 /** OAuth provider configuration */
 const oauthProviderSchema = z.object({
     authUrl: z.string().pipe(z.url()),
@@ -163,6 +176,11 @@ const jeevesConfigSchema = z
      * If omitted, all paths are shareable with outsiders.
      */
     outsiderPolicy: scopesSchema.optional(),
+    /**
+     * Logging configuration.
+     * Not hot-reloadable — changes require a service restart.
+     */
+    logging: loggingConfigSchema.optional(),
     /** OAuth2 credential management configuration */
     oauth: oauthSchema.optional(),
     /**
@@ -249,4 +267,4 @@ const jeevesConfigSchema = z
         validateRefs(outsiderRefs, ['outsiderPolicy']);
 });
 
-export { DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema };
+export { DEPRECATED_CONFIG_PROPS, authModeSchema, authSchema, eventConfigSchema, googleAuthSchema, insiderEntrySchema, isScopeName, jeevesConfigSchema, keyEntrySchema, loggingConfigSchema, oauthProviderSchema, oauthSchema, scopesObjectSchema, scopesSchema };

package/package.json

@@ -1,46 +1,10 @@
 {
-  "name": "@karmaniverous/jeeves-server-core",
-  "version": "0.1.3",
   "author": "Jeeves",
-  "description": "Shared cryptographic utilities and API types for jeeves-server packages.",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/karmaniverous/jeeves-server.git",
-    "directory": "packages/core"
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "prebuild": "npx rimraf dist",
-    "build": "cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .",
-    "test": "vitest run --passWithNoTests",
-    "typecheck": "tsc --noEmit",
-    "changelog": "git-cliff -o CHANGELOG.md",
-    "release": "dotenvx run -f .env.local -- release-it",
-    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
-    "postbuild": "npx rimraf dist/rollup.config.d.ts dist/rollup.config.d.ts.map"
-  },
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/src/index.d.ts",
-        "default": "./dist/src/index.js"
-      }
-    }
-  },
-  "types": "dist/src/index.d.ts",
   "dependencies": {
-    "@karmaniverous/jeeves": "^0.5.11",
+    "@karmaniverous/jeeves": "^0.5.12",
     "zod": "^4.4.3"
   },
+  "description": "Shared cryptographic utilities and API types for jeeves-server packages.",
   "devDependencies": {
     "@dotenvx/dotenvx": "^1.69.1",
     "@rollup/plugin-commonjs": "^29.0.2",
@@ -56,12 +20,28 @@
   "engines": {
     "node": ">=22"
   },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/src/index.d.ts",
+        "default": "./dist/src/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "name": "@karmaniverous/jeeves-server-core",
+  "publishConfig": {
+    "access": "public"
+  },
   "release-it": {
     "git": {
       "changelog": "npx git-cliff --unreleased --strip header",
       "commitMessage": "chore: release @karmaniverous/jeeves-server-core v${version}",
-      "tagName": "core/${version}",
-      "requireBranch": "main"
+      "requireBranch": "main",
+      "tagName": "core/${version}"
     },
     "github": {
       "release": true
@@ -73,18 +53,38 @@
         "npm run test",
         "npm run build"
       ],
-      "before:npm:release": [
-        "npx git-cliff -o CHANGELOG.md",
-        "git add -A"
-      ],
       "after:release": [
         "git switch -c release/core/${version}",
         "git push -u origin release/core/${version}",
         "git switch ${branchName}"
+      ],
+      "before:npm:release": [
+        "npx git-cliff -o CHANGELOG.md",
+        "git add -A"
       ]
     },
     "npm": {
       "publish": true
     }
-  }
+  },
+  "repository": {
+    "directory": "packages/core",
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/jeeves-server.git"
+  },
+  "scripts": {
+    "build": "cross-env NO_COLOR=1 rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "changelog": "git-cliff -o CHANGELOG.md",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "postbuild": "npx rimraf dist/rollup.config.d.ts dist/rollup.config.d.ts.map",
+    "prebuild": "npx rimraf dist",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  },
+  "type": "module",
+  "types": "dist/src/index.d.ts",
+  "version": "0.1.5"
 }