@monosmith/plugin-sdk 0.0.0-stage → 0.1.0

package/host/connect-plugin.use-case.js

@@ -0,0 +1,44 @@
+import { PassThrough } from 'node:stream';
+import { serveStreams } from '../serve/index.js';
+import { PluginClient } from './plugin-client.client.js';
+/**
+ * Performs the handshake with a plugin reachable through a pair of streams.
+ * Closing the client shuts the plugin down and ends the streams; there is no
+ * process to kill.
+ */
+export function connectPlugin(streams, options) {
+    return PluginClient.open({
+        input: streams.input,
+        output: streams.output,
+        kill: () => { streams.output.end(); },
+        finish: () => Promise.resolve(null),
+    }, options);
+}
+/**
+ * Serves a plugin object in this process over pipes and connects to it, the way
+ * the Go SDK's tests serve a plugin with `serve.Serve` over `io.Pipe`: the
+ * real framing, handshake and dispatch, no process. Closing the client waits
+ * for the serve loop to end.
+ */
+export async function connectInProcess(plugin, options) {
+    const toPlugin = new PassThrough();
+    const fromPlugin = new PassThrough();
+    const served = (async () => {
+        try {
+            await serveStreams(plugin, { input: toPlugin, output: fromPlugin, log: () => { } });
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            fromPlugin.end();
+        }
+    })();
+    return await PluginClient.open({
+        input: fromPlugin,
+        output: toPlugin,
+        kill: () => { toPlugin.end(); },
+        finish: () => served,
+    }, options);
+}

package/host/host-options.contract.d.ts

@@ -0,0 +1,28 @@
+import type { Peer } from '../protocol/index.ts';
+/** What the host tells the plugin, and how long it waits. */
+export interface HostOptions {
+    /** The absolute workspace root sent in `initialize`. A plugin that reads manifests resolves them against it. */
+    workspaceRoot: string;
+    /** The host's name and version. Default: `smith`, `dev`. */
+    host?: Peer;
+    /** How long `initialize` may take. Default: 30 seconds. */
+    initializeTimeoutMs?: number;
+}
+/** Options of {@link startPlugin}: a plugin process to launch. */
+export interface StartOptions extends HostOptions {
+    /** The plugin's argv: the program and its arguments. */
+    command: string[];
+    /** The environment. Default: the current one. `SMITH_PLUGIN=1` is set in it unless it already has a value, as smith does. */
+    env?: NodeJS.ProcessEnv;
+    /** The plugin's working directory. Default: the current one. */
+    cwd?: string;
+    /** What happens to the plugin's standard error, where it logs. Default: it goes to this process's standard error. */
+    stderr?: 'inherit' | 'ignore';
+}
+/** The longest a call may take unless the caller says otherwise: generate and publish run real toolchains. */
+export declare const DEFAULT_CALL_TIMEOUT_MS: number;
+/** Options of one {@link PluginClient.call}. */
+export interface CallOptions {
+    /** How long the plugin may take. On expiry the plugin process is killed: its stream can no longer be trusted. Default: 2 minutes. */
+    timeoutMs?: number;
+}

package/host/host-options.contract.js

@@ -0,0 +1,2 @@
+/** The longest a call may take unless the caller says otherwise: generate and publish run real toolchains. */
+export const DEFAULT_CALL_TIMEOUT_MS = 2 * 60 * 1000;

package/host/index.d.ts

@@ -0,0 +1,7 @@
+export { PluginClient } from './plugin-client.client.ts';
+export type { PluginConnection } from './plugin-client.client.ts';
+export { startPlugin } from './start-plugin.use-case.ts';
+export { connectInProcess, connectPlugin } from './connect-plugin.use-case.ts';
+export type { PluginStreams } from './connect-plugin.use-case.ts';
+export { DEFAULT_CALL_TIMEOUT_MS } from './host-options.contract.ts';
+export type { CallOptions, HostOptions, StartOptions } from './host-options.contract.ts';

package/host/index.js

@@ -0,0 +1,4 @@
+export { PluginClient } from './plugin-client.client.js';
+export { startPlugin } from './start-plugin.use-case.js';
+export { connectInProcess, connectPlugin } from './connect-plugin.use-case.js';
+export { DEFAULT_CALL_TIMEOUT_MS } from './host-options.contract.js';

package/host/plugin-client.client.d.ts

@@ -0,0 +1,42 @@
+import type { InitializeResult, MethodName, ParamsOf, ResultOf } from '../protocol/index.ts';
+import type { CallOptions, HostOptions } from './host-options.contract.ts';
+/** The two ends of the pipe to a plugin, and what to do with the plugin when the stream cannot be trusted. */
+export interface PluginConnection {
+    /** The plugin's responses. */
+    input: AsyncIterable<Uint8Array>;
+    /** The plugin's requests. */
+    output: {
+        write: (chunk: Buffer, callback: (error?: Error | null) => void) => unknown;
+        end: () => unknown;
+    };
+    /** Called when a call timed out: ends the plugin, if it is a process. */
+    kill: () => void;
+    /** Resolves once the plugin has gone, with the reason it did not end well (or `null`). Called by {@link PluginClient.close}. */
+    finish: (graceMs: number) => Promise<string | null>;
+}
+/**
+ * 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).
+ */
+export declare class PluginClient {
+    #private;
+    /** Performs the handshake on a connection. */
+    static open(connection: PluginConnection, options: HostOptions): Promise<PluginClient>;
+    /** What the plugin answered to `initialize`: identity, kind, roles, capabilities. */
+    info: InitializeResult;
+    private constructor();
+    /**
+     * Sends one request and resolves with its decoded result. An error answer
+     * rejects with an {@link RpcError} carrying its code. If the plugin does not
+     * answer in time, the plugin is killed and the call rejects.
+     */
+    call<M extends MethodName>(method: M, params: ParamsOf<M>, options?: CallOptions): Promise<ResultOf<M>>;
+    call(method: string, params?: unknown, options?: CallOptions): Promise<unknown>;
+    /** Whether the plugin advertised a method: `initialize` and `shutdown` always, the others by their capability. */
+    supports(method: string): boolean;
+    /** Asks the plugin to shut down and waits briefly for it to go. Rejects if it did not go quietly. */
+    close(): Promise<void>;
+}

package/host/plugin-client.client.js

@@ -0,0 +1,166 @@
+import { decodeResult, encodeParams, parseResponse, writeRequest } from '../codec/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';
+function writeFrame(output, frame) {
+    return new Promise((resolve, reject) => {
+        output.write(frame, (error) => {
+            if (error === null || error === undefined)
+                resolve();
+            else
+                reject(error);
+        });
+    });
+}
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(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).
+ */
+export class PluginClient {
+    /** Performs the handshake on a connection. */
+    static async open(connection, options) {
+        const client = new PluginClient(connection);
+        try {
+            client.info = await client.call('initialize', {
+                protocolVersions: [PROTOCOL_VERSION],
+                host: options.host ?? { name: 'smith', version: 'dev' },
+                workspaceRoot: options.workspaceRoot,
+            }, { timeoutMs: options.initializeTimeoutMs ?? 30_000 });
+        }
+        catch (error) {
+            connection.kill();
+            throw new Error(`initializing plugin: ${messageOf(error)}`, { cause: error });
+        }
+        if (client.info.protocolVersion !== PROTOCOL_VERSION) {
+            connection.kill();
+            throw new Error(`plugin ${client.info.plugin.name} chose protocol version ${client.info.protocolVersion}, host speaks ${PROTOCOL_VERSION}`);
+        }
+        return client;
+    }
+    #connection;
+    #waiter;
+    #lost;
+    #tail = Promise.resolve();
+    #nextId = 0;
+    /** What the plugin answered to `initialize`: identity, kind, roles, capabilities. */
+    info;
+    constructor(connection) {
+        this.#connection = connection;
+        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;
+    }
+    async #send(method, params, timeoutMs) {
+        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 }; });
+        try {
+            await writeFrame(this.#connection.output, frameMessage(body));
+        }
+        catch (error) {
+            this.#waiter = undefined;
+            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);
+        });
+        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`);
+        if ('error' in outcome)
+            throw new Error(`${method}: plugin stopped answering: ${outcome.error.message}`, { cause: outcome.error });
+        try {
+            const response = parseResponse(outcome.body);
+            if (response.error !== null)
+                throw new RpcError(response.error.code, response.error.message);
+            return decodeResult(method, response.result);
+        }
+        catch (error) {
+            if (error instanceof RpcError)
+                throw error;
+            throw new Error(`${method}: plugin stopped answering: ${messageOf(error)}`, { cause: error });
+        }
+    }
+    async #readResponses() {
+        const reader = new FrameReader();
+        try {
+            for await (const chunk of this.#connection.input) {
+                for (const body of reader.push(chunk))
+                    this.#deliver(body);
+            }
+            this.#lose(new Error('EOF'));
+        }
+        catch (error) {
+            this.#lose(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    #deliver(body) {
+        const waiter = this.#waiter;
+        if (waiter === undefined)
+            return;
+        try {
+            if (parseResponse(body).id === waiter.id)
+                waiter.settle({ body });
+            // Responses to other ids cannot happen with serialised calls; skip them.
+        }
+        catch (error) {
+            waiter.settle({ error: new Error(`malformed response: ${messageOf(error)}`, { cause: error }) });
+        }
+    }
+    #lose(error) {
+        this.#lost = error;
+        this.#waiter?.settle({ error });
+    }
+    async call(method, params, options = {}) {
+        return await this.#serialise(() => this.#send(method, params, options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS));
+    }
+    /** 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;
+    }
+    /** Asks the plugin to shut down and waits briefly for it to go. Rejects if it did not go quietly. */
+    async close() {
+        try {
+            await this.call('shutdown', {}, { timeoutMs: 5000 });
+        }
+        catch {
+            // A plugin that is already gone cannot be asked; waiting for it below reports how it went.
+        }
+        this.#connection.output.end();
+        const trouble = await this.#connection.finish(5000);
+        if (trouble !== null)
+            throw new Error(trouble);
+    }
+}

package/host/start-plugin.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { StartOptions } from './host-options.contract.ts';
+import { PluginClient } from './plugin-client.client.ts';
+/**
+ * Launches a plugin process and performs the handshake, as smith does: the
+ * plugin's argv, `SMITH_PLUGIN=1` in its environment, its standard input and
+ * output as the protocol's channel, its standard error forwarded to this
+ * process's. Close the client when done: it asks the plugin to shut down and
+ * kills it if it does not go.
+ */
+export declare function startPlugin(options: StartOptions): Promise<PluginClient>;

package/host/start-plugin.use-case.js

@@ -0,0 +1,57 @@
+import { spawn } from 'node:child_process';
+import { PluginClient } from './plugin-client.client.js';
+/**
+ * Launches a plugin process and performs the handshake, as smith does: the
+ * plugin's argv, `SMITH_PLUGIN=1` in its environment, its standard input and
+ * output as the protocol's channel, its standard error forwarded to this
+ * process's. Close the client when done: it asks the plugin to shut down and
+ * kills it if it does not go.
+ */
+export async function startPlugin(options) {
+    const [program, ...args] = options.command;
+    if (program === undefined)
+        throw new Error('plugin command is empty');
+    const env = { ...(options.env ?? process.env) };
+    env.SMITH_PLUGIN ??= '1';
+    const child = spawn(program, args, { env, cwd: options.cwd, stdio: ['pipe', 'pipe', options.stderr ?? 'inherit'], windowsHide: true });
+    const exited = new Promise((resolve) => {
+        child.once('close', (code, signal) => { resolve({ code, signal }); });
+    });
+    // A program that cannot be started never answers: its streams just end.
+    let spawnFailure;
+    child.once('error', (cause) => { spawnFailure = cause; });
+    // Writing to a plugin that has gone raises EPIPE on stdin; the call that wrote sees the error.
+    child.stdin.on('error', () => { });
+    const connection = {
+        input: child.stdout,
+        output: { write: (chunk, callback) => child.stdin.write(chunk, callback), end: () => child.stdin.end() },
+        kill: () => { child.kill(); },
+        finish: (graceMs) => waitForExit(child, exited, graceMs),
+    };
+    try {
+        return await PluginClient.open(connection, options);
+    }
+    catch (error) {
+        child.kill();
+        await exited;
+        if (spawnFailure === undefined)
+            throw error;
+        throw new Error(`starting plugin ${JSON.stringify(options.command)}: ${spawnFailure.message}`, { cause: error });
+    }
+}
+async function waitForExit(child, exited, graceMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve('timeout');
+        }, graceMs);
+    });
+    const outcome = await Promise.race([exited, timeout]);
+    clearTimeout(timer);
+    if (outcome === 'timeout') {
+        child.kill();
+        await exited;
+        return 'plugin did not exit after shutdown; killed';
+    }
+    return outcome.code === 0 ? null : `plugin exited with ${outcome.signal ?? `status ${outcome.code}`}`;
+}

package/index.d.ts

@@ -0,0 +1,15 @@
+export * from './protocol/index.ts';
+export * from './serve/index.ts';
+export * from './tasks/index.ts';
+export * from './scaffold/index.ts';
+export * from './ci/index.ts';
+export * from './build-dir/index.ts';
+export * from './plugin-roles/index.ts';
+export * from './plugin-refs/index.ts';
+export * from './projects/index.ts';
+export * from './templating/index.ts';
+export * from './jsondoc/index.ts';
+export * from './host/index.ts';
+export * from './conformance/index.ts';
+export { decodeParams, decodeResult, encodeParams, encodeResult, EncodeError, MessageParseError, ParamsError } from './codec/index.ts';
+export { FrameReader, FramingError, frameMessage } from './framing/index.ts';

package/index.js

@@ -0,0 +1,20 @@
+// The public API of @monosmith/plugin-sdk.
+// The protocol: every message as a type, generated from the JSON Schema.
+export * from './protocol/index.js';
+// Writing a plugin.
+export * from './serve/index.js';
+export * from './tasks/index.js';
+export * from './scaffold/index.js';
+export * from './ci/index.js';
+export * from './build-dir/index.js';
+export * from './plugin-roles/index.js';
+export * from './plugin-refs/index.js';
+export * from './projects/index.js';
+export * from './templating/index.js';
+export * from './jsondoc/index.js';
+// Testing a plugin.
+export * from './host/index.js';
+export * from './conformance/index.js';
+// Building blocks: the wire form of the messages, for tools that speak the protocol themselves.
+export { decodeParams, decodeResult, encodeParams, encodeResult, EncodeError, MessageParseError, ParamsError } from './codec/index.js';
+export { FrameReader, FramingError, frameMessage } from './framing/index.js';

package/jsondoc/indent-raw-json.algorithm.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Formats JSON text as Go's `json.Indent(dst, src, prefix, "  ")` does: the
+ * insignificant whitespace is dropped and every element goes on its own line,
+ * indented two spaces per level and starting with `prefix`; an empty array or
+ * object stays `[]` or `{}`. Text that is not an array is returned as it is. The text
+ * of leaves (numbers, strings) is kept exactly.
+ */
+export declare function indentRawJson(raw: string, prefix: string): string;

package/jsondoc/indent-raw-json.algorithm.js

@@ -0,0 +1,60 @@
+/** A string literal (escapes included), a bracket, a comma or colon, or a run of any other characters (a number, `true`, `null`). */
+const TOKEN = /"(?:[^"\\]|\\.)*"|[{}[\],:]|[^\s{}[\],:"]+/g;
+/**
+ * Formats JSON text as Go's `json.Indent(dst, src, prefix, "  ")` does: the
+ * insignificant whitespace is dropped and every element goes on its own line,
+ * indented two spaces per level and starting with `prefix`; an empty array or
+ * object stays `[]` or `{}`. Text that is not an array is returned as it is. The text
+ * of leaves (numbers, strings) is kept exactly.
+ */
+export function indentRawJson(raw, prefix) {
+    if (!raw.startsWith('['))
+        return raw;
+    let out = '';
+    let depth = 0;
+    // Right after an opening bracket: the line break is held back until it is known whether the container is empty.
+    let needIndent = false;
+    const newline = () => {
+        out += `\n${prefix}${'  '.repeat(depth)}`;
+    };
+    const open = (token) => {
+        needIndent = true;
+        out += token;
+    };
+    const close = (token) => {
+        if (needIndent) {
+            needIndent = false;
+        }
+        else {
+            depth--;
+            newline();
+        }
+        out += token;
+    };
+    const handlers = {
+        '{': open,
+        '[': open,
+        '}': close,
+        ']': close,
+        ',': (token) => {
+            out += token;
+            newline();
+        },
+        ':': () => {
+            out += ': ';
+        },
+    };
+    for (const [token] of raw.matchAll(TOKEN)) {
+        if (needIndent && token !== '}' && token !== ']') {
+            needIndent = false;
+            depth++;
+            newline();
+        }
+        const handler = Object.hasOwn(handlers, token) ? handlers[token] : undefined;
+        if (handler === undefined)
+            out += token;
+        else
+            handler(token);
+    }
+    return out;
+}

package/jsondoc/index.d.ts

@@ -0,0 +1,2 @@
+export { JsonDocument } from './json-document.model.ts';
+export { JsonDocumentError } from './json-document.error.ts';

package/jsondoc/index.js

@@ -0,0 +1,2 @@
+export { JsonDocument } from './json-document.model.js';
+export { JsonDocumentError } from './json-document.error.js';

package/jsondoc/json-document.error.d.ts

@@ -0,0 +1,4 @@
+/** The text is not a JSON object, or not JSON at all. */
+export declare class JsonDocumentError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}

package/jsondoc/json-document.error.js

@@ -0,0 +1,7 @@
+/** The text is not a JSON object, or not JSON at all. */
+export class JsonDocumentError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'JsonDocumentError';
+    }
+}

package/jsondoc/json-document.model.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A JSON object that keeps its key order and the text of everything you do not
+ * touch, so editing a `package.json` changes only what was edited: set a
+ * member and it keeps its place, add one and it goes last, delete one and the
+ * others stay where they were. Port of the Go SDK's `jsondoc.Document`.
+ *
+ * ```ts
+ * const doc = JsonDocument.parse(text)
+ * doc.setString('version', '1.2.3')
+ * writeFileSync(path, doc.render())
+ * ```
+ */
+export declare class JsonDocument {
+    #private;
+    /** Reads a JSON object. Throws {@link JsonDocumentError} for anything else. */
+    static parse(text: string): JsonDocument;
+    /** Whether the key exists. */
+    has(key: string): boolean;
+    /** The keys, in order. */
+    keys(): string[];
+    /** The number of keys. */
+    get size(): number;
+    /** The object under a key, editable in place; `create` adds an empty one (last) when there is none. Undefined for a key that holds something else. */
+    object(key: string, create?: boolean): JsonDocument | undefined;
+    /** A string value; undefined when the key is missing or does not hold a string. */
+    getString(key: string): string | undefined;
+    /** Any value under a key as JavaScript sees it, or undefined for a missing key. */
+    getValue(key: string): unknown;
+    /** Sets a string, keeping the key's position. */
+    setString(key: string, value: string): void;
+    /** Sets any JSON-encodable value, keeping the key's position. A plain object becomes an editable document, with its members in the order you wrote them. */
+    setJson(key: string, value: unknown): void;
+    /** Removes a key. */
+    delete(key: string): void;
+    /** The document as npm writes a package.json: two-space indentation, a final newline. */
+    render(): string;
+    toString(): string;
+}

package/jsondoc/json-document.model.js

@@ -0,0 +1,113 @@
+var _a;
+import { indentRawJson } from './indent-raw-json.algorithm.js';
+import { JsonDocumentError } from './json-document.error.js';
+import { scanJsonObject } from './scan-json-object.algorithm.js';
+/** A string as Go's JSON encoder writes it without HTML escaping: JSON, with U+2028 and U+2029 escaped. */
+function quote(text) {
+    return JSON.stringify(text)
+        .replaceAll('\u{2028}', String.raw `\u2028`)
+        .replaceAll('\u{2029}', String.raw `\u2029`);
+}
+/**
+ * A JSON object that keeps its key order and the text of everything you do not
+ * touch, so editing a `package.json` changes only what was edited: set a
+ * member and it keeps its place, add one and it goes last, delete one and the
+ * others stay where they were. Port of the Go SDK's `jsondoc.Document`.
+ *
+ * ```ts
+ * const doc = JsonDocument.parse(text)
+ * doc.setString('version', '1.2.3')
+ * writeFileSync(path, doc.render())
+ * ```
+ */
+export class JsonDocument {
+    /** Reads a JSON object. Throws {@link JsonDocumentError} for anything else. */
+    static parse(text) {
+        return _a.#fromNode(scanJsonObject(text));
+    }
+    static #fromNode(node) {
+        const doc = new _a();
+        for (const [key, value] of node.members)
+            doc.#entries.set(key, value.kind === 'object' ? _a.#fromNode(value) : { raw: value.text });
+        return doc;
+    }
+    /** In the order the keys were first set: a Map keeps it, whatever the keys look like. */
+    #entries = new Map();
+    #write(indent) {
+        if (this.#entries.size === 0)
+            return '{}';
+        const inner = `${indent}  `;
+        const lines = [...this.#entries].map(([key, entry]) => {
+            const value = entry instanceof _a ? entry.#write(inner) : indentRawJson(entry.raw, inner);
+            return `${inner}${quote(key)}: ${value}`;
+        });
+        return `{\n${lines.join(',\n')}\n${indent}}`;
+    }
+    /** Whether the key exists. */
+    has(key) {
+        return this.#entries.has(key);
+    }
+    /** The keys, in order. */
+    keys() {
+        // The es2023 lib this package compiles with has no Iterator#toArray.
+        // eslint-disable-next-line unicorn/prefer-spread
+        return Array.from(this.#entries.keys());
+    }
+    /** The number of keys. */
+    get size() {
+        return this.#entries.size;
+    }
+    /** The object under a key, editable in place; `create` adds an empty one (last) when there is none. Undefined for a key that holds something else. */
+    object(key, create = false) {
+        const entry = this.#entries.get(key);
+        if (entry instanceof _a)
+            return entry;
+        if (!create)
+            return undefined;
+        const child = new _a();
+        this.#entries.set(key, child);
+        return child;
+    }
+    /** A string value; undefined when the key is missing or does not hold a string. */
+    getString(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined || entry instanceof _a)
+            return undefined;
+        const value = JSON.parse(entry.raw);
+        return typeof value === 'string' ? value : undefined;
+    }
+    /** Any value under a key as JavaScript sees it, or undefined for a missing key. */
+    getValue(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined)
+            return undefined;
+        return JSON.parse(entry instanceof _a ? entry.render() : entry.raw);
+    }
+    /** Sets a string, keeping the key's position. */
+    setString(key, value) {
+        this.#entries.set(key, { raw: quote(value) });
+    }
+    /** Sets any JSON-encodable value, keeping the key's position. A plain object becomes an editable document, with its members in the order you wrote them. */
+    setJson(key, value) {
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            this.#entries.set(key, _a.parse(JSON.stringify(value)));
+            return;
+        }
+        const raw = JSON.stringify(value);
+        if (raw === undefined)
+            throw new JsonDocumentError(`${key}: a ${typeof value} cannot be written as JSON`);
+        this.#entries.set(key, { raw });
+    }
+    /** Removes a key. */
+    delete(key) {
+        this.#entries.delete(key);
+    }
+    /** The document as npm writes a package.json: two-space indentation, a final newline. */
+    render() {
+        return `${this.#write('')}\n`;
+    }
+    toString() {
+        return this.render();
+    }
+}
+_a = JsonDocument;