yamlover 0.3.56 → 0.3.58

package/dist/wire/openapi.yo

@@ -0,0 +1,935 @@
+# THE OPENAPI DOCUMENT of the yamlover wire (docs/server/wire) — authored in yamlover (OpenAPI is
+# YAML, and yamlover reads it), served as JSON at `GET /api/openapi` and printed by
+# `npx yamlover --print-openapi`. Two things are filled in when it is served (wire-openapi.ts):
+# `info.version` from wire-version.ts, and `components.schemas` from the `$defs` meta files this
+# document names in `x-yamlover-defs` — the schemas live ONCE, in `$defs/`, and this document
+# only refers to them. The routes are the CONTRACT and CONVENIENCE families of the inventory
+# (docs/server/wire, the routes); the private surface (doctor, reindex, tasks, config,
+# agent-docs) is deliberately absent. Status codes are quoted — a bare integer key is a position
+# in yamlover, not a string.
+openapi: 3.1.0
+info:
+  title: the yamlover wire
+  version: '0'   # replaced by WIRE_VERSION when served
+  description: >
+    The HTTP protocol between a yamlover server and its clients. A node is read as a yamlover
+    document (the content envelope), edited by batches of surgical text edits, and every change -
+    a client's or an external one - is pushed as a diff on one event stream. Paths in parameters
+    and bodies are colon paths (`:a:b:0`); only `/api/content/{path}` takes a slash path.
+x-yamlover-defs:
+  - envelope
+  - link
+  - edit
+  - edit-batch
+  - edit-answer
+  - event
+servers:
+  - url: /
+    description: the local server (`npx yamlover <root>`), or the deployment's `--base-path`
+tags:
+  - name: contract
+    description: the model - what any client needs and any server answers
+  - name: convenience
+    description: derived helpers a second client may skip or compute for itself
+components:
+  parameters:
+    path:
+      name: path
+      in: query
+      description: a colon path (`:a:b:0`); absent or `:` is the root
+      schema:
+        type: string
+    depth:
+      name: depth
+      in: query
+      description: the document-boundary budget - an integer, or `.inf`; absent picks the node's default (unlimited for a text document, 1 for a directory or a binary)
+      schema:
+        type: string
+  responses:
+    refused:
+      description: the request was refused or needs recovery; an explicit recovery conflict preserves its journal and competing external bytes
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+          example:
+            error: 'unknown edit op: frobnicate'
+    notFound:
+      description: the path names no node
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              error:
+                type: string
+paths:
+  /api/info:
+    get:
+      tags: [contract]
+      summary: the root title, the read-only flag and the wire version
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  root:
+                    type: string
+                  readOnly:
+                    type: boolean
+                  wire:
+                    type: integer
+              example:
+                root: yamlover
+                readOnly: false
+                wire: 1
+  '/api/content/{path}':
+    get:
+      tags: [contract]
+      summary: THE ONE WIRE - the node as a content envelope
+      description: >
+        Answers `text/yamlover`: the node's authored text under a store-derived header, with the
+        sidecar and the relations panel - `$defs/envelope`. `path` is a SLASH path here (the URL);
+        `/api/content` alone is the root.
+      parameters:
+        - name: path
+          in: path
+          required: true
+          description: 'the node''s slash path, segments percent-encoded; a position that is the slot of a pull link walks THROUGH it (`host/11` is the card `- *:: elsewhere: card.yo` names, `host/11/0` its first element) - the envelope''s `path` is then the walked path and `canonical` where the node lives'
+          schema:
+            type: string
+        - $ref: '#/components/parameters/depth'
+        - name: editing
+          in: query
+          description: use 1 to reconcile source and return a revision for guarded saves
+          schema:
+            type: string
+        - name: range
+          in: query
+          description: 'the window over the top node''s rendered entries - `A-B`, `A-`, `-B`, `.len-(N)-` (the range grammar minus `.`); a node past 1000 entries auto-windows to `0-500` without it'
+          schema:
+            type: string
+      responses:
+        '200':
+          description: the content envelope
+          headers:
+            X-Yamlover-Revision:
+              description: project SHA-256 revision, only when editing=1
+              schema:
+                type: string
+          content:
+            text/yamlover:
+              schema:
+                $ref: '#/components/schemas/envelope'
+              example: |
+                wire: 2
+                path: :notes:todo.yo
+                documentPath: :notes:todo.yo
+                type: object
+                hasKeyed: true
+                hasOrdinal: false
+                concrete: file/yamlover
+                title: todo
+                depth: .inf
+                source: |
+                  title: todo
+                  items: *: items
+                side:
+                  "": {}
+                  \/items:
+                    member: true
+                    stub:
+                      $yamloverLink: {kind: array, type: array, hasKeyed: false, hasOrdinal: true, path: :notes:todo.yo:items, concrete: yamlover, hasChildren: true, count: 3}
+                relations:
+                  ..:
+                    $yamloverLink: {kind: omni, type: omni, path: :notes, format: x-yamlover-chapter, concrete: dir/index.yo, hasChildren: true, count: 2, title: Notes}
+                  ':: ...: ?#: pet: $':
+                    $yamloverLink: {kind: omni, type: omni, path: :team:alice, concrete: yamlover, hasChildren: true, count: 3}
+        '404':
+          $ref: '#/components/responses/notFound'
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/blob:
+    get:
+      tags: [contract]
+      summary: the raw bytes of a file-backed node, with single byte-range support
+      parameters:
+        - $ref: '#/components/parameters/path'
+        - name: Range
+          in: header
+          schema: {type: string}
+        - name: If-Range
+          in: header
+          schema: {type: string}
+      responses:
+        '200':
+          description: the bytes, Content-Type from the format; Accept-Ranges, Content-Length and ETag
+          content:
+            '*/*':
+              schema: {type: string, format: binary}
+        '206':
+          description: the requested byte range, with Content-Range
+        '416':
+          description: invalid or unsatisfiable byte range
+        '404':
+          $ref: '#/components/responses/notFound'
+    head:
+      tags: [contract]
+      summary: file headers without the body
+      parameters:
+        - $ref: '#/components/parameters/path'
+      responses:
+        '200':
+          description: Content-Type, Content-Length, Accept-Ranges and ETag
+        '404':
+          $ref: '#/components/responses/notFound'
+  /api/tree:
+    get:
+      tags: [contract]
+      summary: the TOC projection of a subtree
+      parameters:
+        - $ref: '#/components/parameters/path'
+        - name: depth
+          in: query
+          description: levels of the tree (default 3)
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: a TreeNode - label, path, type, children; a truncation as `notLoaded`
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  path:
+                    type: string
+                  label:
+                    type: string
+                  children:
+                    type: array
+                    items:
+                      type: object
+        '404':
+          $ref: '#/components/responses/notFound'
+  /api/source:
+    get:
+      tags: [contract]
+      summary: the node's yamlover source, as authored
+      parameters:
+        - $ref: '#/components/parameters/path'
+      responses:
+        '200':
+          description: ok
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  source:
+                    type: string
+              example:
+                source: "a: 1\nb: hello\n"
+        '404':
+          $ref: '#/components/responses/notFound'
+  /api/schema:
+    get:
+      tags: [contract]
+      summary: the projected instance schema of a node
+      parameters:
+        - $ref: '#/components/parameters/path'
+        - $ref: '#/components/parameters/depth'
+      responses:
+        '200':
+          description: the schema projection (yamlover meta as JSON)
+          content:
+            application/json:
+              schema:
+                type: object
+  /api/query:
+    get:
+      tags: [contract]
+      summary: evaluate a query
+      parameters:
+        - name: q
+          in: query
+          required: true
+          description: the query, in the colon grammar (docs/language/pointers/queries)
+          schema:
+            type: string
+        - $ref: '#/components/parameters/path'
+        - name: shape
+          in: query
+          description: absent - matching paths; `tree` - one TreeNode per match; `filter` - the tree filtered to the matches
+          schema:
+            type: string
+            enum: [tree, filter]
+      responses:
+        '200':
+          description: the matches
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  results:
+                    type: array
+                  root:
+                    type: object
+                  matches:
+                    type: array
+                    items:
+                      type: string
+                  truncated:
+                    type: boolean
+              example:
+                results: [':notes:todo.yo', ':notes:done.yo']
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/events:
+    get:
+      tags: [contract]
+      summary: the event stream - every change, as it lands
+      description: '`text/event-stream`: one `$defs/event` per `data:` frame; `: connected` then a `hello` frame on connect, `: ping` every 30 s. No replay - but a reconnect whose `hello` names the same `instance` and `seq` it last saw missed nothing and keeps what it holds; anything else means everything loaded is stale.'
+      responses:
+        '200':
+          description: the stream
+          content:
+            text/event-stream:
+              schema:
+                $ref: '#/components/schemas/event'
+              example: |
+                : connected
+
+                data: {"type":"diff","added":[],"changed":[":notes:todo.yo"],"removed":[],"moved":[]}
+
+                data: {"type":"task","task":{"id":"index","label":"indexing","state":"done","progress":{"done":12,"total":12},"startedAt":1756400000000,"finishedAt":1756400000400}}
+  /api/undo:
+    post:
+      tags: [contract]
+      summary: reverse a recorded operation; redo reverses the undo operation
+      description: >
+        Requires safety revision and request identity. Preserves files and references through
+        the mutation journal; conflicts rather than overwriting intervening changes. Receipts
+        and undo data expire after 30 days. The returned operationId identifies the inverse.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [operationId, safety]
+              properties:
+                operationId:
+                  type: string
+                safety:
+                  type: object
+                  required: [revision, operationId]
+                  properties:
+                    revision:
+                      type: string
+                    operationId:
+                      type: string
+      responses:
+        '200':
+          description: the inverse committed or its original result was replayed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/edit-answer'
+        '409':
+          description: changed source, reused identity or already reversed operation
+        '410':
+          description: undo history expired or unavailable
+        '428':
+          description: revision and request identity required
+  /api/edit:
+    post:
+      tags: [contract]
+      summary: a batch of surgical edits
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/edit-batch'
+            example:
+              edits:
+                - {path: ':notes:todo.yo:title', op: emplace, yamlover: 'todo, revised'}
+                - {path: ':notes', op: insert, concrete: file/yamlover, name: done, yamlover: 'title: done'}
+      responses:
+        '200':
+          description: the batch folded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/edit-answer'
+              example:
+                ok: true
+                path: :notes:done.yo
+        '400':
+          $ref: '#/components/responses/refused'
+        '409':
+          description: stale source revision, reused identity with different payload, or recovery conflict
+        '410':
+          description: operation identity expired; reconcile before submitting a new operation
+        '428':
+          description: safety was supplied without a valid revision
+  /api/link:
+    post:
+      tags: [contract]
+      summary: link a node into a target's body - the node stays, the target gains a pointer element to it
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              members:
+                from:
+                  type: string
+                  description: the node to link (a file or directory path)
+                to:
+                  type: string
+                  description: the chapter, task or directory whose body gains the pointer
+      responses:
+        '200':
+          description: the target and the pointer text appended
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/unlink:
+    post:
+      tags: [contract]
+      summary: delete a LINKED node's slot - the pointer entry goes, references to that place follow the node
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              members:
+                path:
+                  type: string
+                  description: the link's slot - the holder's path plus the pointer entry's position (or key)
+      responses:
+        '200':
+          description: the removed slot, the node's actual path, the references rewritten, the reindex diff
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/mv:
+    post:
+      tags: [contract]
+      summary: move a file or directory, relinking what pointed at it
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                from:
+                  type: string
+                to:
+                  type: string
+            example:
+              from: :notes:todo.yo
+              to: :archive:todo.yo
+      responses:
+        '200':
+          description: the move report and the index diff
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/rekey:
+    post:
+      tags: [contract]
+      summary: rename a key in place, relinking what pointed at it — keyless → keyed and back too
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                path:
+                  type: string
+                  description: the entry — by its key, or by its POSITION when a keyless chunk takes a key
+                key:
+                  type: string
+                  nullable: true
+                  description: the new key; `null` DROPS it — the entry turns keyless in place (the key cell's dash); `title` and hidden overlay keys are refused
+            example:
+              path: :notes:todo.yo:title
+              key: heading
+      responses:
+        '200':
+          description: the new path, the relink report and the diff
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  path:
+                    type: string
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/paste:
+    post:
+      tags: [contract]
+      summary: file clipboard content beside a node
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+      responses:
+        '201':
+          description: what was born
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/annotations:
+    get:
+      tags: [contract]
+      summary: the annotations on a material
+      parameters:
+        - $ref: '#/components/parameters/path'
+      responses:
+        '200':
+          description: the tag applications, with their fragments
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+  /api/annotate:
+    post:
+      tags: [contract]
+      summary: apply a tag to a node or a fragment of it
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                target:
+                  type: string
+                  description: the NODE to tag — a walked path (`:session:5`, a card through its slot) resolves to the node it names; the bookmark lands in that node's own document, never in the host's
+                tag:
+                  type: string
+                selector:
+                  type: object
+            example:
+              target: :notes:todo.yo
+              tag: :yamlover:ontos:workflow:dev:ready
+      responses:
+        '201':
+          description: applied
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+        '400':
+          $ref: '#/components/responses/refused'
+    delete:
+      tags: [contract]
+      summary: remove a tag application
+      parameters:
+        - name: target
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: tag
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: selector
+          in: query
+          description: the fragment's selector as JSON, when the application is on a fragment
+          schema:
+            type: string
+      responses:
+        '200':
+          description: removed
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/fragment:
+    post:
+      tags: [contract]
+      summary: mark a region of a material, with no tag yet
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                target:
+                  type: string
+                selector:
+                  type: object
+      responses:
+        '201':
+          description: the fragment made
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/tagged:
+    get:
+      tags: [contract]
+      summary: the materials filed under a tag
+      parameters:
+        - $ref: '#/components/parameters/path'
+      responses:
+        '200':
+          description: the targets
+          content:
+            application/json:
+              schema:
+                type: array
+        '404':
+          $ref: '#/components/responses/notFound'
+  /api/tag:
+    post:
+      tags: [contract]
+      summary: create a tag in the project taxonomy (or find it)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                name:
+                  type: string
+      responses:
+        '201':
+          description: the tag
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  path:
+                    type: string
+                  name:
+                    type: string
+                  color:
+                    type: string
+                  created:
+                    type: boolean
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/workflows:
+    get:
+      tags: [contract]
+      summary: every workflow the index holds
+      description: >-
+        Each `x-yamlover-workflow` node, the bundled taxonomy's included, projected as a tag ref -
+        the task page's workflow picker.
+      responses:
+        '200':
+          description: the workflows, in path order
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  workflows:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        path: { type: string }
+                        name: { type: string }
+                        color: { type: [string, 'null'] }
+  /api/board:
+    get:
+      tags: [contract]
+      summary: a task's board - its subtasks in lanes
+      parameters:
+        - $ref: '#/components/parameters/path'
+      responses:
+        '200':
+          description: the resolved board
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  seeded:
+                    type: boolean
+                  workflow:
+                    description: >-
+                      the workflow the lanes read - `own: true` when the task's own `workflow:`
+                      field names it, else inherited from the nearest ancestor task; null when none
+                    type: [object, 'null']
+                    properties:
+                      path: { type: string }
+                      name: { type: string }
+                      color: { type: [string, 'null'] }
+                      own: { type: boolean }
+        '404':
+          $ref: '#/components/responses/notFound'
+    post:
+      tags: [contract]
+      summary: move a card, save the layout, or reconcile the board
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                path:
+                  type: string
+                op:
+                  type: string
+                  enum: [structure, move, reconcile]
+                structure:
+                  type: array
+                task:
+                  type: string
+                from:
+                  type: object
+                to:
+                  type: object
+      responses:
+        '201':
+          description: the resolved board
+          content:
+            application/json:
+              schema:
+                type: object
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/dangling:
+    get:
+      tags: [contract]
+      summary: the pointers that did not resolve at index time
+      responses:
+        '200':
+          description: the list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    from:
+                      type: string
+                    raw:
+                      type: string
+                    reason:
+                      type: string
+  /api/video:
+    get:
+      tags: [convenience]
+      summary: prepare an MP4 for frame playback, or stream its playable bytes
+      description: >-
+        Requires ffmpeg and ffprobe. Non-H.264 videos receive a cached H.264 preview under .yo/videos.
+        Completed metadata and previews survive restart; changed or deleted sources invalidate them.
+        Read-only servers reuse existing products without writing caches.
+        Concurrent work is shared; original files are unchanged. Frame timestamps describe
+        the playable stream, in seconds. Byte streaming accepts the same Range and If-Range
+        headers as /api/blob. HEAD with stream=1 returns stream headers only.
+      parameters:
+        - $ref: '#/components/parameters/path'
+        - name: stream
+          in: query
+          schema: {type: string, enum: ['1']}
+        - name: Range
+          in: header
+          schema: {type: string}
+        - name: If-Range
+          in: header
+          schema: {type: string}
+      responses:
+        '200':
+          description: metadata, or the playable MP4 when stream=1
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [duration, frames, width, height, codec, preview, revision]
+                properties:
+                  duration: {type: number}
+                  frames:
+                    type: array
+                    items: {type: number}
+                  width: {type: integer}
+                  height: {type: integer}
+                  codec: {type: string}
+                  preview: {type: boolean}
+                  revision: {type: string}
+            video/mp4:
+              schema: {type: string, format: binary}
+        '206':
+          description: playable stream byte range
+        '416':
+          description: unsatisfiable stream byte range
+        '415':
+          description: not an MP4
+        '503':
+          description: preparation failed, including missing FFmpeg
+        '404':
+          $ref: '#/components/responses/notFound'
+  /api/thumb:
+    get:
+      tags: [convenience]
+      summary: a thumbnail of a file-backed blob, generated once and cached beside it
+      parameters:
+        - $ref: '#/components/parameters/path'
+        - name: w
+          in: query
+          schema:
+            type: integer
+        - name: h
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: the image
+          content:
+            image/jpeg: {}
+            image/png: {}
+        '415':
+          description: no decoder for the format
+        '404':
+          $ref: '#/components/responses/notFound'
+  /api/cards:
+    get:
+      tags: [convenience]
+      summary: board card stubs for a list of paths
+      description: >-
+        Each path is resolved by the engine exactly as /api/content walks it: a pointer's slot
+        (`:task-sessions:1` for `- *: '20260829'`) answers the card of the task behind it, with
+        `path` as asked and `canonical` naming where the task lives when the two differ. A path
+        naming no node answers an inert stub, never an error.
+      parameters:
+        - name: paths
+          in: query
+          required: true
+          description: comma-separated colon paths
+          schema:
+            type: string
+      responses:
+        '200':
+          description: one stub per path
+          content:
+            application/json:
+              schema:
+                type: array
+  /api/preview:
+    post:
+      tags: [convenience]
+      summary: the content envelope of a standalone text (stateless)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                source:
+                  type: string
+      responses:
+        '200':
+          description: the envelope
+          content:
+            text/yamlover:
+              schema:
+                $ref: '#/components/schemas/envelope'
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/edit-text:
+    post:
+      tags: [convenience]
+      summary: an edit batch applied to a standalone text (stateless)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                source:
+                  type: string
+                edits:
+                  type: array
+                  items:
+                    $ref: '#/components/schemas/edit'
+      responses:
+        '200':
+          description: the text after the batch
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  source:
+                    type: string
+        '400':
+          $ref: '#/components/responses/refused'
+  /api/dead-links:
+    get:
+      tags: [convenience]
+      summary: the in-tree links the doctor found dead
+      responses:
+        '200':
+          description: the targets
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  targets:
+                    type: array
+  /api/openapi:
+    get:
+      tags: [convenience]
+      summary: this document
+      responses:
+        '200':
+          description: the OpenAPI document, `info.version` the wire version
+          content:
+            application/json:
+              schema:
+                type: object