@monosmith/plugin-sdk 0.1.0 → 0.2.1

package/host/plugin-client.client.js

@@ -1,7 +1,9 @@
-import { decodeResult, encodeParams, parseResponse, writeRequest } from '../codec/index.js';
+import { decodeResult, encodeParams, parseResponse, writeNotification, writeRequest } from '../codec/index.js';
+import { inFlightLimit } from '../concurrency/index.js';
 import { FrameReader, frameMessage } from '../framing/index.js';
 import { PROTOCOL_VERSION, RpcError, protocolSchema } from '../protocol/index.js';
-import { DEFAULT_CALL_TIMEOUT_MS } from './host-options.contract.js';
+import { CallInterruptedError } from './call-interrupted.error.js';
+import { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_CANCEL_GRACE_MS } from './host-options.contract.js';
 function writeFrame(output, frame) {
     return new Promise((resolve, reject) => {
         output.write(frame, (error) => {
@@ -17,15 +19,18 @@ function messageOf(thrown) {
 }
 /**
  * The host's side of a connection to one initialized plugin, for a plugin
- * author's tests (smith itself is the host in real use). Calls are serialised,
- * as smith serialises them, each with a timeout. Open one with {@link startPlugin}
- * (a process), {@link connectPlugin} (streams) or {@link connectInProcess}
- * (a plugin object served in this process).
+ * author's tests (smith itself is the host in real use). It never has more
+ * requests in flight than the plugin declared in `concurrency`, as smith does:
+ * with the default of one, calls are serialised, each waiting for the one
+ * before it to be answered. Each call has a timeout and may be cancelled with
+ * an `AbortSignal`. Open one with {@link startPlugin} (a process),
+ * {@link connectPlugin} (streams) or {@link connectInProcess} (a plugin object
+ * served in this process).
  */
 export class PluginClient {
     /** Performs the handshake on a connection. */
     static async open(connection, options) {
-        const client = new PluginClient(connection);
+        const client = new PluginClient(connection, options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS);
         try {
             client.info = await client.call('initialize', {
                 protocolVersions: [PROTOCOL_VERSION],
@@ -41,61 +46,97 @@ export class PluginClient {
             connection.kill();
             throw new Error(`plugin ${client.info.plugin.name} chose protocol version ${client.info.protocolVersion}, host speaks ${PROTOCOL_VERSION}`);
         }
+        client.#limit = inFlightLimit(client.info.concurrency);
         return client;
     }
     #connection;
-    #waiter;
+    #waiters = new Map();
+    #queue = [];
+    #graceMs;
     #lost;
-    #tail = Promise.resolve();
     #nextId = 0;
+    #limit = 1;
+    #inFlight = 0;
+    #peak = 0;
     /** What the plugin answered to `initialize`: identity, kind, roles, capabilities. */
     info;
-    constructor(connection) {
+    constructor(connection, graceMs) {
         this.#connection = connection;
+        this.#graceMs = graceMs;
         void this.#readResponses();
     }
-    /** Runs a task after the ones before it, whatever became of them. */
-    async #serialise(task) {
-        const previous = this.#tail;
-        const current = (async () => {
-            await previous;
-            return await task();
-        })();
-        this.#tail = (async () => {
-            try {
-                await current;
-            }
-            catch {
-                // The caller of this task sees the failure; the next one only waits.
-            }
-        })();
-        return await current;
+    /** Waits for a place among the requests that may be in flight; rejects if `signal` aborts first. */
+    #acquire(signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(new CallInterruptedError('cancelled before it was sent', 'cancelled', false));
+        if (this.#inFlight < this.#limit) {
+            this.#take();
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                grant: () => {
+                    signal?.removeEventListener('abort', onAbort);
+                    this.#take();
+                    resolve();
+                },
+            };
+            const onAbort = () => {
+                const at = this.#queue.indexOf(entry);
+                if (at !== -1)
+                    this.#queue.splice(at, 1);
+                reject(new CallInterruptedError('cancelled before it was sent', 'cancelled', false));
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.#queue.push(entry);
+        });
+    }
+    #take() {
+        this.#inFlight++;
+        this.#peak = Math.max(this.#peak, this.#inFlight);
     }
-    async #send(method, params, timeoutMs) {
+    #release() {
+        this.#inFlight--;
+        this.#queue.shift()?.grant();
+    }
+    async #send(method, params, timeoutMs, signal) {
         if (this.#lost !== undefined)
             throw new Error(`${method}: plugin stopped answering: ${this.#lost.message}`, { cause: this.#lost });
         const id = ++this.#nextId;
         const body = writeRequest(id, method, params === undefined ? undefined : encodeParams(method, params));
-        const answer = new Promise((resolve) => { this.#waiter = { id, settle: resolve }; });
+        const answer = new Promise((resolve) => { this.#waiters.set(id, { settle: resolve }); });
         try {
             await writeFrame(this.#connection.output, frameMessage(body));
         }
         catch (error) {
-            this.#waiter = undefined;
+            this.#waiters.delete(id);
             throw new Error(`${method}: plugin is not accepting requests: ${messageOf(error)}`, { cause: error });
         }
         let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(() => {
-                this.#connection.kill();
-                resolve({ timedOut: true });
-            }, timeoutMs);
+        let onAbort;
+        const interrupted = new Promise((resolve) => {
+            timer = setTimeout(() => { resolve('timeout'); }, timeoutMs);
+            onAbort = () => { resolve('cancelled'); };
+            if (signal?.aborted === true)
+                resolve('cancelled');
+            else
+                signal?.addEventListener('abort', onAbort, { once: true });
         });
-        const outcome = await Promise.race([answer, timeout]);
-        clearTimeout(timer);
-        this.#waiter = undefined;
-        if ('timedOut' in outcome)
-            throw new Error(`${method}: plugin did not answer within ${timeoutMs}ms`);
+        try {
+            const winner = await Promise.race([answer, interrupted]);
+            if (typeof winner !== 'string') {
+                this.#waiters.delete(id);
+                return this.#decode(method, winner);
+            }
+            return await this.#giveUp(method, id, answer, winner, timeoutMs);
+        }
+        finally {
+            clearTimeout(timer);
+            if (onAbort !== undefined)
+                signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    #decode(method, outcome) {
         if ('error' in outcome)
             throw new Error(`${method}: plugin stopped answering: ${outcome.error.message}`, { cause: outcome.error });
         try {
@@ -110,6 +151,51 @@ export class PluginClient {
             throw new Error(`${method}: plugin stopped answering: ${messageOf(error)}`, { cause: error });
         }
     }
+    /**
+     * The end of a call whose signal aborted or whose time ran out. A plugin that
+     * advertised cancel is sent the notification and has the grace period to
+     * answer; one that cannot be asked is killed at once when the time ran out,
+     * and after the grace period when the caller cancelled. A plugin that does not
+     * answer in time is killed, and every other call in flight to it fails.
+     */
+    async #giveUp(method, id, answer, reason, timeoutMs) {
+        const asked = this.supports('cancel');
+        if (asked) {
+            try {
+                await this.notify('cancel', { id });
+            }
+            catch {
+                // The plugin is gone; waiting for the answer below reports how it went.
+            }
+        }
+        if (asked || reason === 'cancelled') {
+            let timer;
+            const grace = new Promise((resolve) => {
+                timer = setTimeout(() => { resolve('expired'); }, this.#graceMs);
+            });
+            const winner = await Promise.race([answer, grace]);
+            clearTimeout(timer);
+            if (winner !== 'expired') {
+                this.#waiters.delete(id);
+                return this.#answeredAfterStopping(method, winner, reason, timeoutMs);
+            }
+        }
+        this.#waiters.delete(id);
+        this.#connection.kill();
+        if (reason === 'timeout')
+            throw new CallInterruptedError(`${method}: plugin did not answer within ${timeoutMs}ms`, reason, true);
+        throw new CallInterruptedError(`${method}: cancelled; the plugin did not stop within ${this.#graceMs}ms and was killed`, reason, true);
+    }
+    /** The plugin answered while the host was giving up: a result is the work finished in time, and is the call's result. */
+    #answeredAfterStopping(method, outcome, reason, timeoutMs) {
+        try {
+            return this.#decode(method, outcome);
+        }
+        catch (error) {
+            const what = reason === 'timeout' ? `did not answer within ${timeoutMs}ms` : 'cancelled';
+            throw new CallInterruptedError(`${method}: ${what}: ${messageOf(error)}`, reason, false, error instanceof RpcError ? error : undefined);
+        }
+    }
     async #readResponses() {
         const reader = new FrameReader();
         try {
@@ -124,31 +210,76 @@ export class PluginClient {
         }
     }
     #deliver(body) {
-        const waiter = this.#waiter;
-        if (waiter === undefined)
-            return;
+        let id;
         try {
-            if (parseResponse(body).id === waiter.id)
-                waiter.settle({ body });
-            // Responses to other ids cannot happen with serialised calls; skip them.
+            id = parseResponse(body).id;
         }
         catch (error) {
-            waiter.settle({ error: new Error(`malformed response: ${messageOf(error)}`, { cause: error }) });
+            // A malformed response cannot be attributed to a call: the stream is lost.
+            this.#lose(new Error(`malformed response: ${messageOf(error)}`, { cause: error }));
+            return;
         }
+        if (id === null)
+            return;
+        const waiter = this.#waiters.get(id);
+        if (waiter === undefined)
+            return;
+        this.#waiters.delete(id);
+        waiter.settle({ body });
     }
     #lose(error) {
         this.#lost = error;
-        this.#waiter?.settle({ error });
+        const waiting = this.#waiters;
+        this.#waiters = new Map();
+        for (const waiter of waiting.values())
+            waiter.settle({ error });
     }
     async call(method, params, options = {}) {
-        return await this.#serialise(() => this.#send(method, params, options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS));
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+        if (method === 'shutdown')
+            return await this.#send(method, params, timeoutMs, options.signal); // it must reach a plugin that is busy
+        try {
+            await this.#acquire(options.signal);
+        }
+        catch (error) {
+            if (error instanceof CallInterruptedError)
+                throw new CallInterruptedError(`${method}: ${error.message}`, error.reason, false);
+            throw error;
+        }
+        try {
+            return await this.#send(method, params, timeoutMs, options.signal);
+        }
+        finally {
+            this.#release();
+        }
+    }
+    /** How long the plugin has to answer after it was asked to stop. */
+    get cancelGraceMs() {
+        return this.#graceMs;
+    }
+    /** The most requests this client has had in flight at once. */
+    get peakInFlight() {
+        return this.#peak;
+    }
+    /** Sends a message that gets no answer, such as `cancel`. */
+    async notify(method, params) {
+        if (this.#lost !== undefined)
+            throw new Error(`${method}: plugin stopped answering: ${this.#lost.message}`, { cause: this.#lost });
+        try {
+            const body = writeNotification(method, encodeParams(method, params));
+            await writeFrame(this.#connection.output, frameMessage(body));
+        }
+        catch (error) {
+            throw new Error(`${method}: plugin is not accepting requests: ${messageOf(error)}`, { cause: error });
+        }
     }
     /** Whether the plugin advertised a method: `initialize` and `shutdown` always, the others by their capability. */
     supports(method) {
         if (method === 'initialize' || method === 'shutdown')
             return true;
         const capability = Object.hasOwn(protocolSchema['x-methods'], method) ? protocolSchema['x-methods'][method].capability : null;
-        return capability !== null && this.info.capabilities[capability] === true;
+        const advertised = this.info?.capabilities;
+        return capability !== null && advertised?.[capability] === true;
     }
     /** Asks the plugin to shut down and waits briefly for it to go. Rejects if it did not go quietly. */
     async close() {

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from './protocol/index.ts';
 export * from './serve/index.ts';
+export * from './concurrency/index.ts';
 export * from './tasks/index.ts';
 export * from './scaffold/index.ts';
 export * from './ci/index.ts';

package/index.js

@@ -3,6 +3,7 @@
 export * from './protocol/index.js';
 // Writing a plugin.
 export * from './serve/index.js';
+export * from './concurrency/index.js';
 export * from './tasks/index.js';
 export * from './scaffold/index.js';
 export * from './ci/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monosmith/plugin-sdk",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The TypeScript SDK for writing smith plugins: the protocol's types, the serve loop, a test host, the conformance checks, templating and key-order-keeping JSON editing. No runtime dependencies.",
   "license": "MIT",
   "type": "module",

package/protocol/protocol-schema.contract.js

@@ -3,7 +3,7 @@ export const protocolSchema = {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://raw.githubusercontent.com/monosmith-app/monosmith/main/packages/plugin-sdk/schema/protocol.schema.json",
     "title": "smith plugin protocol",
-    "description": "The messages of the smith plugin protocol: JSON-RPC 2.0 between the smith host and a plugin, a separate process. This file is generated from the Go types of packages/plugin-sdk/protocol, which are the source of truth; do not edit it. Regenerate it with `go run ./schemagen` in packages/plugin-sdk.\n\nx-methods maps each method name to the definitions of its params and result and to the capability a plugin advertises to be asked it (null: always available). x-errorCodes, x-roles and x-transport complete the contract. A definition's required members are the ones the Go SDK writes without omitempty.\n\nFraming: each message is the header Content-Length: <bytes of the body>, a blank line (CRLF CRLF) and the body, UTF-8 JSON, as the Language Server Protocol frames. The length counts bytes, not characters. The host sends initialize first, calls one plugin at a time, and a request with an id gets exactly one response with the same id. A request without an id is a notification and gets none. Stdout carries only frames: a plugin logs to stderr. The host sets SMITH_PLUGIN=1 in the plugin's environment.\n\nReading: a receiver ignores members it does not know (the protocol grows by adding members), and treats a null array or object as an empty one, because the Go SDK writes a nil slice or map as null when the member is required. A member that is absent and a member with its zero value are the same for every optional member.\n\nPaths in messages are relative to the workspace and use forward slashes; only workspaceRoot is absolute and uses the host's separators.",
+    "description": "The messages of the smith plugin protocol: JSON-RPC 2.0 between the smith host and a plugin, a separate process. This file is generated from the Go types of packages/plugin-sdk/protocol, which are the source of truth; do not edit it. Regenerate it with `go run ./schemagen` in packages/plugin-sdk.\n\nx-methods maps each method name to the definitions of its params and result and to the capability a plugin advertises to be asked it (null: always available). x-errorCodes, x-roles and x-transport complete the contract. A definition's required members are the ones the Go SDK writes without omitempty.\n\nFraming: each message is the header Content-Length: <bytes of the body>, a blank line (CRLF CRLF) and the body, UTF-8 JSON, as the Language Server Protocol frames. The length counts bytes, not characters. The host sends initialize first, and a request with an id gets exactly one response with the same id. A request without an id is a notification and gets none. The host has at most as many requests in flight to a plugin as its initialize result declares in concurrency (absent: 1, the next request is sent after the previous is answered); responses may come in any order, matched by id. A plugin that advertised the cancel capability is sent the cancel notification for a request the host gives up on, and answers that request with its result or the request-cancelled error; a plugin without it is never sent cancel. Stdout carries only frames: a plugin logs to stderr. The host sets SMITH_PLUGIN=1 in the plugin's environment.\n\nReading: a receiver ignores members it does not know (the protocol grows by adding members), and treats a null array or object as an empty one, because the Go SDK writes a nil slice or map as null when the member is required. A member that is absent and a member with its zero value are the same for every optional member.\n\nPaths in messages are relative to the workspace and use forward slashes; only workspaceRoot is absolute and uses the host's separators.",
     "x-protocolVersion": 1,
     "x-transport": {
         "framing": "content-length",
@@ -20,7 +20,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/InitializeResult"
             },
-            "capability": null
+            "capability": null,
+            "notification": false
         },
         "shutdown": {
             "description": "The last request. The plugin answers an empty object and exits.",
@@ -30,7 +31,17 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/Empty"
             },
-            "capability": null
+            "capability": null,
+            "notification": false
+        },
+        "cancel": {
+            "description": "A notification, so it gets no response: the host asks the plugin to stop the in-flight request with the given id. The plugin then answers that request, with its result if the work was already done or with the request-cancelled error. An id that is unknown or already answered is ignored. The host sends it only to a plugin that advertised the capability.",
+            "params": {
+                "$ref": "#/$defs/CancelParams"
+            },
+            "result": null,
+            "capability": "cancel",
+            "notification": true
         },
         "discover": {
             "description": "Describes the projects behind manifests the host found; a language plugin's way into the workspace.",
@@ -40,7 +51,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/DiscoverResult"
             },
-            "capability": "discover"
+            "capability": "discover",
+            "notification": false
         },
         "generate": {
             "description": "Writes the starter files of a new project.",
@@ -50,7 +62,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/GenerateResult"
             },
-            "capability": "generate"
+            "capability": "generate",
+            "notification": false
         },
         "version/write": {
             "description": "Records a release version in a project's manifest.",
@@ -60,7 +73,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/VersionResult"
             },
-            "capability": "version"
+            "capability": "version",
+            "notification": false
         },
         "publish": {
             "description": "Publishes one project at one version, or builds the files attached to a release.",
@@ -70,7 +84,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/PublishResult"
             },
-            "capability": "publish"
+            "capability": "publish",
+            "notification": false
         },
         "ci": {
             "description": "Describes what a generated pipeline needs for the plugin's projects.",
@@ -80,7 +95,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/CIResult"
             },
-            "capability": "ci"
+            "capability": "ci",
+            "notification": false
         },
         "doctor": {
             "description": "Checks the plugin's projects and reports findings, each with its remedy and, optionally, a fix.",
@@ -90,7 +106,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/DoctorResult"
             },
-            "capability": "doctor"
+            "capability": "doctor",
+            "notification": false
         },
         "contribute": {
             "description": "Asks a convention (toolchain, structure, deploy) for the tasks and dependencies it adds to projects other plugins discovered.",
@@ -100,7 +117,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/ContributeResult"
             },
-            "capability": "contribute"
+            "capability": "contribute",
+            "notification": false
         },
         "remove": {
             "description": "Lets a plugin clean up what it owns outside a project's directory after the project is removed.",
@@ -110,7 +128,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/RemoveResult"
             },
-            "capability": "remove"
+            "capability": "remove",
+            "notification": false
         },
         "published": {
             "description": "Asks which version of a project its registry has, so a release can check its tags against it.",
@@ -120,7 +139,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/PublishedResult"
             },
-            "capability": "published"
+            "capability": "published",
+            "notification": false
         },
         "dependencies/install": {
             "description": "Adds packages to a project with the ecosystem's own toolchain, or, with no project, installs every dependency of the projects the plugin serves.",
@@ -130,7 +150,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/DependencyResult"
             },
-            "capability": "dependencies"
+            "capability": "dependencies",
+            "notification": false
         },
         "dependencies/uninstall": {
             "description": "Removes packages from a project.",
@@ -140,7 +161,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/DependencyResult"
             },
-            "capability": "dependencies"
+            "capability": "dependencies",
+            "notification": false
         },
         "dependencies/declared": {
             "description": "Lists the dependencies the manifests of the plugin's projects declare.",
@@ -150,7 +172,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/DeclaredResult"
             },
-            "capability": "declarations"
+            "capability": "declarations",
+            "notification": false
         },
         "dependencies/rewrite": {
             "description": "Changes declared dependency specs in place.",
@@ -160,7 +183,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/DependencyResult"
             },
-            "capability": "declarations"
+            "capability": "declarations",
+            "notification": false
         },
         "dependencies/latest": {
             "description": "Asks registries for the newest releases of dependencies, and how the tools the plugin pins compare with theirs.",
@@ -170,7 +194,8 @@ export const protocolSchema = {
             "result": {
                 "$ref": "#/$defs/LatestResult"
             },
-            "capability": "latest"
+            "capability": "latest",
+            "notification": false
         }
     },
     "x-errorCodes": [
@@ -203,6 +228,11 @@ export const protocolSchema = {
             "name": "PluginFailure",
             "code": -32000,
             "description": "The method ran and failed for a reason the user must act on (a missing toolchain, a bad manifest). The message is shown to the user as it is, so it should say what to do. An error a method of the Go SDK returns becomes this code."
+        },
+        {
+            "name": "RequestCancelled",
+            "code": -32800,
+            "description": "The plugin stopped the request because the host sent a cancel notification for its id. A plugin that had finished answers with the result instead. Only a plugin that advertised the cancel capability sends it; when a cancelled request fails with any error, the SDKs answer with this code."
         }
     ],
     "x-roles": [
@@ -424,6 +454,19 @@ export const protocolSchema = {
                 }
             }
         },
+        "CancelParams": {
+            "description": "CancelParams are the params of the cancel notification.",
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "integer",
+                    "description": "ID is the id of the in-flight request to stop. An id the plugin does not know, or whose request is already answered, is ignored."
+                }
+            },
+            "required": [
+                "id"
+            ]
+        },
         "Capabilities": {
             "description": "Capabilities are the optional methods a plugin implements.",
             "type": "object",
@@ -469,6 +512,10 @@ export const protocolSchema = {
                 "latest": {
                     "type": "boolean",
                     "description": "Latest reports the newest releases of dependencies and pinned tools."
+                },
+                "cancel": {
+                    "type": "boolean",
+                    "description": "Cancel says the plugin stops the work of a request when the host sends a cancel notification with its id, then answers that request with its result (if the work was already done) or the request-cancelled error. A host never sends the notification to a plugin without it."
                 }
             }
         },
@@ -943,6 +990,10 @@ export const protocolSchema = {
                         "type": "string"
                     },
                     "description": "Notes are printed to the user after generation."
+                },
+                "installPending": {
+                    "type": "boolean",
+                    "description": "InstallPending is true when the plugin changed what the workspace depends on and left installing it to the host. A project is made by several plugins in turn; the host asks each plugin that reported this to install once (dependencies/install with Quiet set) after the last of them has generated, instead of once per plugin."
                 }
             },
             "required": [
@@ -991,6 +1042,10 @@ export const protocolSchema = {
                 "capabilities": {
                     "$ref": "#/$defs/Capabilities"
                 },
+                "concurrency": {
+                    "type": "integer",
+                    "description": "Concurrency is how many requests the plugin can work on at the same time; the host never has more in flight. Absent or 0 means 1, which is what every plugin that says nothing does: the host sends the next request only after the previous one is answered. N above 1 allows that many, and ConcurrencyUnlimited (-1) leaves the number to the host. Any other negative value is invalid and read as 1."
+                },
                 "languages": {
                     "type": "array",
                     "items": {
@@ -1089,6 +1144,10 @@ export const protocolSchema = {
                 "dev": {
                     "type": "boolean",
                     "description": "Dev adds them as development dependencies where the ecosystem has such a thing; a plugin without one says so in a note."
+                },
+                "quiet": {
+                    "type": "boolean",
+                    "description": "Quiet keeps the package manager's output unless it fails: the host sets it when it installs as one step of a larger job (smith add)."
                 }
             }
         },