@toa.io/extensions.exposition 1.0.0-alpha.284 → 1.0.0-alpha.286

package/source/directives/map/Map.ts

@@ -21,37 +21,50 @@ export class Map implements DirectiveFamily {
 
   private remotes!: Remotes
 
-  public create (name: string, value: unknown, remotes: Remotes): Property | Mapping {
+  public create(name: string, value: unknown, remotes: Remotes): Property | Mapping {
     this.remotes = remotes
 
-    return match(name,
-      () => properties.has(name), (name: PN) => new Property(name, value as PV),
-      () => name in mappings, (name: keyof typeof mappings) => new mappings[name](value, remotes),
+    return match(
+      name,
+      () => properties.has(name),
+      (name: PN) => new Property(name, value as PV),
+      () => name in mappings,
+      (name: keyof typeof mappings) => new mappings[name](value, remotes),
       () => {
         throw new Error(`Directive 'map:${name}' is not implemented`)
-      })
+      }
+    )
   }
 
-  public explain (directives: Directive[], _: Input, introspection: Introspection): Introspection {
+  public explain(
+    directives: Directive[],
+    _: Input,
+    introspection: Introspection
+  ): Introspection {
     for (const directive of directives)
-      if (directive instanceof Mapping)
-        directive.explain(introspection)
+      if (directive instanceof Mapping) directive.explain(introspection)
 
     return introspection
   }
 
-  public async precall (directives: Directive[], context: Input, parameters: Parameter[]): Promise<Output> {
+  public async precall(
+    directives: Directive[],
+    context: Input,
+    parameters: Parameter[]
+  ): Promise<Output> {
     const properties = {}
 
     for (const directive of directives)
       if (directive instanceof Mapping)
-        Object.assign(properties, await directive.properties(context, parameters, directives))
+        Object.assign(
+          properties,
+          await directive.properties(context, parameters, directives)
+        )
 
     context.pipelines.body.push((body: unknown) => {
       if (body === undefined || body === null || typeof body !== 'object')
         return properties
-      else
-        return Object.assign(body, properties)
+      else return Object.assign(body, properties)
     })
 
     return null

package/source/directives/map/Mapping.ts

@@ -9,12 +9,16 @@ export abstract class Mapping<T = unknown> {
   protected value: T
   protected remotes?: Remotes
 
-  protected constructor (value: T, remotes?: Remotes) {
+  protected constructor(value: T, remotes?: Remotes) {
     this.value = value
     this.remotes = remotes
   }
 
-  public abstract properties (context: Input, parameters: Parameter[], directives: Directive[]): Output
+  public abstract properties(
+    context: Input,
+    parameters: Parameter[],
+    directives: Directive[]
+  ): Output
 
   /**
    * What this mapping does to what the method says about itself, which is the reverse of
@@ -25,13 +29,12 @@ export abstract class Mapping<T = unknown> {
    * from the request itself and there is nowhere for a caller to put one; a header and a
    * segment are the caller's, and those say where.
    */
-  public explain (introspection: Introspection): void {
-    for (const property of this.names())
-      take(introspection, property)
+  public explain(introspection: Introspection): void {
+    for (const property of this.names()) take(introspection, property)
   }
 
   /** The input properties this mapping fills, however its value names them. */
-  protected names (): string[] {
+  protected names(): string[] {
     return typeof this.value === 'string'
       ? [this.value]
       : Object.keys(this.value as object)

package/source/directives/map/Properties.ts

@@ -6,7 +6,7 @@ export class Property<K extends keyof Properties = keyof Properties> {
   public readonly name: K
   public readonly value: Properties[K]
 
-  public constructor (name: K, value: Properties[K]) {
+  public constructor(name: K, value: Properties[K]) {
     this.name = name
     this.value = value
   }

package/source/directives/map/Segments.ts

@@ -5,17 +5,19 @@ import type { Parameter } from '../../RTD/index.js'
 import type { Introspection, Schema } from '../../Introspection.js'
 
 export class Segments extends Mapping<Record<string, string>> {
-  public constructor (map: Record<string, string>) {
+  public constructor(map: Record<string, string>) {
     assert.ok(map.constructor === Object, '`map:segments` must be an object')
 
-    assert.ok(Object.values(map).every((value) => typeof value === 'string'),
-      '`map:segments ` must be an object with string values')
+    assert.ok(
+      Object.values(map).every((value) => typeof value === 'string'),
+      '`map:segments ` must be an object with string values'
+    )
 
     super(map)
   }
 
   /** A segment is the caller's, so it moves to the route rather than out of sight. */
-  public override explain (introspection: Introspection): void {
+  public override explain(introspection: Introspection): void {
     for (const property of Object.keys(this.value)) {
       const schema = take(introspection, property)
 
@@ -24,22 +26,27 @@ export class Segments extends Mapping<Record<string, string>> {
     }
   }
 
-  public override properties (_: unknown, parameters: Parameter[]): Record<string, string> {
-    return Object.entries(this.value).reduce((properties: Record<string, string>, [property, parameter]) => {
-      const cut = parameter[0] === '~'
+  public override properties(
+    _: unknown,
+    parameters: Parameter[]
+  ): Record<string, string> {
+    return Object.entries(this.value).reduce(
+      (properties: Record<string, string>, [property, parameter]) => {
+        const cut = parameter[0] === '~'
 
-      if (cut) parameter = parameter.slice(1)
+        if (cut) parameter = parameter.slice(1)
 
-      const index = parameters.findIndex(({ name }) => name === parameter)
+        const index = parameters.findIndex(({ name }) => name === parameter)
 
-      assert.ok(index > -1, `Route parameter '${parameter}' is missing`)
+        assert.ok(index > -1, `Route parameter '${parameter}' is missing`)
 
-      properties[property] = parameters[index].value
+        properties[property] = parameters[index].value
 
-      if (cut)
-        parameters.splice(index, 1)
+        if (cut) parameters.splice(index, 1)
 
-      return properties
-    }, {})
+        return properties
+      },
+      {}
+    )
   }
 }

package/source/directives/mcp/MCP.ts

@@ -12,22 +12,31 @@ export class MCP implements DirectiveFamily<Tool> {
   public readonly mandatory = false
 
   /** What this method is published as, which is what the nearest declaration says. */
-  public static published (directives: Tool[] | undefined): Tool | null {
+  public static published(directives: Tool[] | undefined): Tool | null {
     return directives?.[0] ?? null
   }
 
   // eslint-disable-next-line max-params
-  public create (name: string, value: unknown, _: unknown, route: string): Tool {
+  public create(name: string, value: unknown, _: unknown, route: string): Tool {
     assert.ok(name === 'tool', `Unknown directive: mcp:${name}`)
 
     return new Tool(value, route)
   }
 
   /** What the route states this method is, which is the only thing that states it. */
-  public explain (directives: Tool[], _: Context,
-    introspection: Introspection): Introspection {
+  public explain(
+    directives: Tool[],
+    _: Context,
+    introspection: Introspection
+  ): Introspection {
     const tool = MCP.published(directives)
 
-    return tool === null ? introspection : { ...introspection, description: tool.description }
+    if (tool === null) return introspection
+
+    return {
+      ...introspection,
+      description: tool.description,
+      ...(tool.title === undefined ? {} : { title: tool.title })
+    }
   }
 }

package/source/directives/mcp/Tool.test.ts

@@ -5,8 +5,38 @@ import { MCP } from './MCP.js'
 
 describe('mcp:tool', () => {
   it('should take what the route states the tool is', () => {
-    assert.strictEqual(new Tool('The pots that are hot.', '/pots/hot').description,
-      'The pots that are hot.')
+    const tool = new Tool('The pots that are hot.', '/pots/hot')
+
+    assert.strictEqual(tool.description, 'The pots that are hot.')
+    assert.strictEqual(tool.title, undefined)
+  })
+
+  it('should take a title beside the description', () => {
+    const tool = new Tool(
+      { title: 'Hot pots', description: 'The pots that are hot.' },
+      '/pots'
+    )
+
+    assert.strictEqual(tool.title, 'Hot pots')
+    assert.strictEqual(tool.description, 'The pots that are hot.')
+  })
+
+  it('should not accept a mapping without a description', () => {
+    assert.throws(() => new Tool({ title: 'Hot pots' }, '/pots'), /cannot be empty/)
+  })
+
+  it('should not accept an empty title', () => {
+    assert.throws(
+      () => new Tool({ title: ' ', description: 'A pot.' }, '/pots'),
+      /a title cannot be empty/
+    )
+  })
+
+  it('should not accept what it does not know', () => {
+    assert.throws(
+      () => new Tool({ description: 'A pot.', name: 'pots' }, '/pots'),
+      /unknown 'name'/
+    )
   })
 
   it('should not accept an empty description', () => {
@@ -18,6 +48,7 @@ describe('mcp:tool', () => {
     assert.throws(() => new Tool(true, '/pots'), /the value is what the tool is/)
     assert.throws(() => new Tool(false, '/pots'), /the value is what the tool is/)
     assert.throws(() => new Tool(1, '/pots'), /the value is what the tool is/)
+    assert.throws(() => new Tool(['A pot.'], '/pots'), /the value is what the tool is/)
   })
 
   it('should refuse a route no name can spell', () => {
@@ -49,8 +80,11 @@ describe('mcp:tool inheritance', () => {
   })
 
   it('should describe a method with what the route states', () => {
-    const described = family.explain([new Tool('What the route is.', '/pots')], null as never,
-      { description: 'What the operation is.' })
+    const described = family.explain(
+      [new Tool('What the route is.', '/pots')],
+      null as never,
+      { description: 'What the operation is.' }
+    )
 
     assert.strictEqual(described.description, 'What the route is.')
   })
@@ -60,7 +94,9 @@ describe('mcp:tool inheritance', () => {
   })
 
   it('should refuse a directive it does not know', () => {
-    assert.throws(() => family.create('resource', 'A pot.', null, '/pots'),
-      /Unknown directive: mcp:resource/)
+    assert.throws(
+      () => family.create('resource', 'A pot.', null, '/pots'),
+      /Unknown directive: mcp:resource/
+    )
   })
 })

package/source/directives/mcp/Tool.ts

@@ -7,22 +7,53 @@ import { segment } from '../../RTD/segment.js'
  * says is what it says it is: a tool a model cannot read the purpose of is one it cannot
  * choose, so there is no way to publish one that states nothing.
  *
+ * A `title` is what a person is shown where a client lists what it may call — a name is an
+ * address and reads as one. A description alone is written as the value; both are written as
+ * a mapping.
+ *
  * The operation states what it is too, and that is not this. An operation is written without
  * knowledge of any route, and a tool is an operation and a route together — the same
- * operation mounted twice is two tools, and one sentence cannot be true of both.
+ * operation mounted twice is two tools, and one sentence is not true of both.
  */
 export class Tool {
   public readonly description: string
+  public readonly title: string | undefined
+
+  public constructor(value: unknown, route: string) {
+    const stated = typeof value === 'string' ? { description: value } : value
+
+    assert.ok(
+      typeof stated === 'object' && stated !== null && !Array.isArray(stated),
+      'Directive mcp:tool: the value is what the tool is, or a `title` and a `description`'
+    )
+
+    const { description, title, ...rest } = stated as Record<string, unknown>
+
+    assert.ok(
+      Object.keys(rest).length === 0,
+      `Directive mcp:tool: unknown ${Object.keys(rest)
+        .map((key) => `'${key}'`)
+        .join(', ')}`
+    )
+
+    assert.ok(
+      typeof description === 'string' && description.trim().length > 0,
+      'Directive mcp:tool: a description cannot be empty'
+    )
 
-  public constructor (value: unknown, route: string) {
-    assert.ok(typeof value === 'string' && value.trim().length > 0,
-      'Directive mcp:tool: the value is what the tool is, which cannot be empty')
+    assert.ok(
+      title === undefined || (typeof title === 'string' && title.trim().length > 0),
+      'Directive mcp:tool: a title cannot be empty'
+    )
 
     // a tool is called by name, so a route that cannot be named cannot be one — said where
     // the mistake is, rather than as a tool that is quietly never listed
-    assert.ok(refusal(segment(route)) === null,
-      `Directive mcp:tool: '${route}' holds a segment no tool name can spell`)
+    assert.ok(
+      refusal(segment(route)) === null,
+      `Directive mcp:tool: '${route}' holds a segment no tool name can spell`
+    )
 
-    this.description = value
+    this.description = description
+    this.title = title as string | undefined
   }
 }

package/source/directives/oauth/Discovery.ts

@@ -20,11 +20,10 @@ export class Discovery implements Interceptor {
    */
   private readonly authorities = new Map<string, Documents>()
 
-  public mount (options: http.Options): void {
+  public mount(options: http.Options): void {
     this.authorities.clear()
 
-    if (options.oauth === undefined)
-      return
+    if (options.oauth === undefined) return
 
     /*
      * `https` always: RFC 8414 has an issuer be one, and OAuth 2.1 has every endpoint of an
@@ -39,20 +38,18 @@ export class Discovery implements Interceptor {
       this.authorities.set(authority, documents(`https://${host}`, options.oauth))
   }
 
-  public reset (): void {
+  public reset(): void {
     this.authorities.clear()
   }
 
-  public intercept (input: Input): Output {
+  public intercept(input: Input): Output {
     const known = this.authorities.get(input.authority)
 
-    if (known === undefined)
-      return null
+    if (known === undefined) return null
 
     // every reply, not just a document's: the challenge is what points a client here
     input.pipelines.response.push((response) => {
-      if (response.status !== UNAUTHORIZED)
-        return
+      if (response.status !== UNAUTHORIZED) return
 
       response.headers ??= new Headers()
       response.headers.set('www-authenticate', known.challenge(input.url.pathname))
@@ -60,8 +57,7 @@ export class Discovery implements Interceptor {
 
     const body = known.read(input.url.pathname)
 
-    if (body === undefined)
-      return null
+    if (body === undefined) return null
 
     return { body, headers: new Headers({ 'cache-control': 'public, max-age=3600' }) }
   }

package/source/directives/oauth/documents.ts

@@ -9,12 +9,12 @@ export interface Documents {
   challenge: (pathname: string) => string
 }
 
-export function documents (issuer: string, oauth: OAuth): Documents {
+export function documents(issuer: string, oauth: OAuth): Documents {
   const server = authorizationServer(issuer, oauth)
   const resources = protectedResources(issuer, oauth)
   const scope = oauth.scopes === undefined ? '' : `, scope="${oauth.scopes.join(' ')}"`
 
-  function read (pathname: string): object | undefined {
+  function read(pathname: string): object | undefined {
     if (pathname === AUTHORIZATION_SERVER || pathname === OPENID_CONFIGURATION)
       return server
 
@@ -24,7 +24,7 @@ export function documents (issuer: string, oauth: OAuth): Documents {
     return undefined
   }
 
-  function challenge (pathname: string): string {
+  function challenge(pathname: string): string {
     return `Bearer resource_metadata="${issuer}${PROTECTED_RESOURCE}${suffix(oauth, pathname)}"${scope}`
   }
 
@@ -36,7 +36,7 @@ export function documents (issuer: string, oauth: OAuth): Documents {
  * everything else this extension serves. Both flags are load-bearing for a client that
  * prefers Client ID Metadata Documents: without either it falls back to registration.
  */
-function authorizationServer (issuer: string, oauth: OAuth): object {
+function authorizationServer(issuer: string, oauth: OAuth): object {
   const metadata: Record<string, unknown> = {
     issuer,
     authorization_endpoint: oauth.authorize,
@@ -52,8 +52,7 @@ function authorizationServer (issuer: string, oauth: OAuth): object {
   if (oauth.registration === 'open')
     metadata.registration_endpoint = `${issuer}${REGISTRATION}`
 
-  if (oauth.scopes !== undefined)
-    metadata.scopes_supported = oauth.scopes
+  if (oauth.scopes !== undefined) metadata.scopes_supported = oauth.scopes
 
   return metadata
 }
@@ -63,7 +62,7 @@ function authorizationServer (issuer: string, oauth: OAuth): object {
  * `https://host/mcp` reads `/.well-known/oauth-protected-resource/mcp`, and one that names
  * no path reads the document at the origin.
  */
-function protectedResources (issuer: string, oauth: OAuth): Map<string, object> {
+function protectedResources(issuer: string, oauth: OAuth): Map<string, object> {
   const map = new Map<string, object>()
 
   for (const path of oauth.resources ?? [])
@@ -74,26 +73,24 @@ function protectedResources (issuer: string, oauth: OAuth): Map<string, object>
   return map
 }
 
-function resource (issuer: string, path: string, oauth: OAuth): object {
+function resource(issuer: string, path: string, oauth: OAuth): object {
   const metadata: Record<string, unknown> = {
     resource: issuer + path,
     authorization_servers: [issuer],
     bearer_methods_supported: ['header']
   }
 
-  if (oauth.scopes !== undefined)
-    metadata.scopes_supported = oauth.scopes
+  if (oauth.scopes !== undefined) metadata.scopes_supported = oauth.scopes
 
   return metadata
 }
 
 /** The document a request to this path was refused against: the longest resource holding it. */
-function suffix (oauth: OAuth, pathname: string): string {
+function suffix(oauth: OAuth, pathname: string): string {
   let longest = ''
 
   for (const path of oauth.resources ?? [])
-    if (pathname.startsWith(path) && path.length > longest.length)
-      longest = path
+    if (pathname.startsWith(path) && path.length > longest.length) longest = path
 
   return canonical(longest)
 }
@@ -102,7 +99,7 @@ function suffix (oauth: OAuth, pathname: string): string {
  * A resource is identified without its trailing slash — the form MCP asks for — while a
  * route is declared with one, so `/mcp/` identifies `…/mcp`.
  */
-function canonical (path: string): string {
+function canonical(path: string): string {
   return path.endsWith('/') ? path.slice(0, -1) : path
 }
 

package/source/directives/octets/Context.ts

@@ -6,15 +6,18 @@ export class Context extends Directive {
   public readonly targeted = false
   public readonly storage: string
 
-  public constructor (value: unknown) {
+  public constructor(value: unknown) {
     super()
 
-    assert.ok(typeof value === 'string', 'Directive \'octets:context\' must must be a string')
+    assert.ok(
+      typeof value === 'string',
+      "Directive 'octets:context' must must be a string"
+    )
 
     this.storage = value
   }
 
-  public async apply (): Promise<Output> {
+  public async apply(): Promise<Output> {
     return null
   }
 }

package/source/directives/octets/Delete.ts

@@ -5,7 +5,7 @@ import { Workflow } from './workflows/index.js'
 import { Directive } from './Directive.js'
 import type { Parameter } from '../../RTD/index.js'
 import type { Unit, Location } from './workflows/index.js'
-import type { Maybe } from '@toa.io/core'
+import type { Maybe } from '@toa.io/core/types'
 import type { Component } from '@toa.io/core'
 import type { Output } from '../../io.js'
 import type { Input } from './types.js'
@@ -19,7 +19,11 @@ export class Delete extends Directive {
   private readonly discovery: Promise<Component>
   private storage!: Component
 
-  public constructor (options: Options | null, discovery: Promise<Component>, remotes: Remotes) {
+  public constructor(
+    options: Options | null,
+    discovery: Promise<Component>,
+    remotes: Remotes
+  ) {
     super()
     schemas.remove.validate(options)
 
@@ -29,43 +33,48 @@ export class Delete extends Directive {
     this.discovery = discovery
   }
 
-  public async apply (storage: string, input: Input, parameters: Parameter[]): Promise<Output> {
+  public async apply(
+    storage: string,
+    input: Input,
+    parameters: Parameter[]
+  ): Promise<Output> {
     this.storage ??= await this.discovery
 
     const output: Output = {}
 
     if (this.workflow !== undefined) {
-      const entry = await this.storage.invoke<Maybe<Entry>>('head',
-        {
-          input: {
-            storage,
-            path: input.request.url
-          }
-        })
+      const entry = await this.storage.invoke<Maybe<Entry>>('head', {
+        input: {
+          storage,
+          path: input.request.url
+        }
+      })
 
-      if (entry instanceof Error)
-        throw new NotFound()
+      if (entry instanceof Error) throw new NotFound()
 
       output.status = 202
       output.body = Readable.from(this.execute(input, storage, entry, parameters))
-    } else
-      await this.delete(storage, input)
+    } else await this.delete(storage, input)
 
     return output
   }
 
-  private async delete (storage: string, input: Input): Promise<void> {
-    await this.storage.invoke('delete',
-      {
-        input: {
-          storage,
-          path: input.request.url
-        }
-      })
+  private async delete(storage: string, input: Input): Promise<void> {
+    await this.storage.invoke('delete', {
+      input: {
+        storage,
+        path: input.request.url
+      }
+    })
   }
 
   // eslint-disable-next-line max-params
-  private async * execute (input: Input, storage: string, entry: Entry, parameters: Parameter[]): AsyncGenerator {
+  private async *execute(
+    input: Input,
+    storage: string,
+    entry: Entry,
+    parameters: Parameter[]
+  ): AsyncGenerator {
     const location: Location = {
       storage,
       authority: input.authority,
@@ -75,8 +84,7 @@ export class Delete extends Directive {
     for await (const chunk of this.workflow!.execute(location, entry, parameters)) {
       yield chunk
 
-      if (typeof chunk === 'object' && chunk !== null && 'error' in chunk)
-        return
+      if (typeof chunk === 'object' && chunk !== null && 'error' in chunk) return
     }
 
     await this.delete(storage, input)

package/source/directives/octets/Directive.ts

@@ -6,5 +6,9 @@ export abstract class Directive {
   public readonly name = 'octets.' + this.constructor.name.toLowerCase()
   public abstract readonly targeted: boolean
 
-  public abstract apply (storage: string, input: Input, parameters: Parameter[]): Promise<io.Output>
+  public abstract apply(
+    storage: string,
+    input: Input,
+    parameters: Parameter[]
+  ): Promise<io.Output>
 }