@karmaniverous/jeeves-server-core 0.4.0 → 0.5.0

package/package.json

@@ -1,24 +1,26 @@
 {
   "author": "Jeeves",
   "dependencies": {
-    "@karmaniverous/jeeves": "0.7.0",
+    "@karmaniverous/jeeves": "^0.11.0",
     "zod": "^4.6.7"
   },
-  "description": "Shared cryptographic utilities and API types for jeeves-server packages.",
+  "description": "Endpoint catalog, OpenAPI document, error codes, config schema and shared key utilities for jeeves-server packages.",
   "devDependencies": {
-    "@dotenvx/dotenvx": "^2.35.0",
+    "@dotenvx/dotenvx": "^2.38.2",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-typescript": "^12.3.0",
+    "@rollup/plugin-typescript": "^12.3.1",
+    "@seriousme/openapi-schema-validator": "^2.12.0",
     "cross-env": "^10.1.0",
-    "release-it": "^21.1.1",
-    "rollup": "^4.64.6",
-    "tslib": "^2.8.1",
-    "vitest": "^5.0.4"
+    "release-it": "^21.1.2",
+    "rollup": "^4.68.3",
+    "tslib": "^2.9.1",
+    "vitest": "^5.1.0",
+    "zod-openapi": "^6.0.2"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24.22.2"
   },
   "exports": {
     ".": {
@@ -26,10 +28,18 @@
         "types": "./dist/src/index.d.ts",
         "default": "./dist/src/index.js"
       }
-    }
+    },
+    "./catalog": {
+      "import": {
+        "types": "./dist/src/catalog/index.d.ts",
+        "default": "./dist/src/catalog/index.js"
+      }
+    },
+    "./openapi.json": "./openapi.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "openapi.json"
   ],
   "license": "MIT",
   "name": "@karmaniverous/jeeves-server-core",
@@ -52,7 +62,9 @@
       "after:bump": [
         "npx git-cliff --tag core/${version} -o CHANGELOG.md",
         "npm install --package-lock-only --ignore-scripts",
-        "git add ../../package-lock.json"
+        "npm run openapi",
+        "npm run build",
+        "git add ../../package-lock.json openapi.json"
       ],
       "after:init": [
         "npm run lint",
@@ -83,6 +95,7 @@
     "changelog": "git-cliff -o CHANGELOG.md",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
+    "openapi": "tsx scripts/write-openapi.ts",
     "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",
@@ -92,5 +105,5 @@
   },
   "type": "module",
   "types": "dist/src/index.d.ts",
-  "version": "0.4.0"
+  "version": "0.5.0"
 }

package/dist/src/endpoints.d.ts

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,248 +0,0 @@
-/**
- * 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,
-    },
-    health: {
-        method: 'GET',
-        path: '/health',
-        description: 'Liveness check: returns { ok: true }, no downstream checks.',
-        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; the response reports whether the path is a directory (isDirectory).',
-        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.).',
-    },
-    'resolve-path': {
-        method: 'GET',
-        path: '/api/resolve-path',
-        description: 'Map an absolute filesystem path to its browse path and URLs (?fsPath=).',
-        insiderOnly: true,
-    },
-    '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 (insiders with no scopes configured; limit capped at 100).',
-        insiderOnly: true,
-    },
-    // --- 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 };