dsh-better-chat/docs/openapi.yaml

83 lines
2.8 KiB
YAML

openapi: 3.0.3
info:
title: dsh-better-chat
version: 1.0.0
description: >
Exact routes registered by apply() in src/host.ts.
POST /better-display/reveal is createRevealHandler in src/reveal.ts.
GET /better-display/metrics returns metricsPayload().
The host webServer mounts these paths. The handlers do not read an
Authorization header or any other credential.
servers:
- url: /
description: DeepSeek Harness host after this plugin has loaded.
paths:
/better-display/reveal:
post:
operationId: revealInFileManager
summary: Reveal a workspace file in the OS file manager
description: >
Any method other than POST returns 405 with an empty body and no
Content-Type. The JSON body is read to completion, then parsed.
An absolute path is used as-is and does not call the workspace root
lookup. A relative path must resolve to exactly one existing file
under the session cwd or the matching workspace registry roots.
Drive-relative and root-relative Windows paths are rejected.
On success the host spawns open -R, explorer.exe /select, or xdg-open.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [path]
properties:
path:
type: string
description: Trimmed. Empty or whitespace-only is 400.
sessionId:
type: string
description: Optional. Used only when path is not absolute.
examples:
relative:
value:
path: docs/report.md
sessionId: target
responses:
'200':
description: The file manager was spawned. Body is JSON.
content:
application/json:
schema:
type: object
required: [ok]
additionalProperties: false
properties:
ok:
type: boolean
enum: [true]
'400':
description: >
JSON.parse failed, path was empty, the path was not
workspace-relative, no root contained the file, or more than one
root contained it. error is String(err), so it includes the
Error prefix.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
'405':
description: req.method was not POST. Empty body. Content-Type is not set.
components:
schemas:
ErrorBody:
type: object
required: [ok, error]
additionalProperties: false
properties:
ok:
type: boolean
enum: [false]
error:
type: string