@wirebench/engine 2.1.1

package/dist/grpc/command.js

@@ -0,0 +1,91 @@
+/**
+ * The command-line equivalent of a call, for the Code panel: what a person would type at a shell
+ * to make the same call with a command-line gRPC client that takes JSON and `.proto` files. The
+ * same value the send path uses is what is rendered, so what the panel shows is what would be sent;
+ * credentials are replaced with a stand-in unless the caller says otherwise.
+ */
+import { quoteForShell } from '../http/curl.js';
+/** The stand-in a redacted secret is rendered as. */
+export const GRPC_COMMAND_REDACTED = '<redacted>';
+/** Header names whose values are secrets whatever the request calls them. */
+const SECRET_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie']);
+function headerRows(input, redact) {
+    const rows = [];
+    for (const [name, value] of Object.entries(input.defaultMetadata ?? {})) {
+        rows.push({ name, value, enabled: true });
+    }
+    if (input.auth !== undefined) {
+        switch (input.auth.type) {
+            case 'bearer':
+                rows.push({
+                    name: 'authorization',
+                    value: `${input.auth.scheme ?? 'Bearer'} ${redact ? GRPC_COMMAND_REDACTED : input.auth.token}`,
+                    enabled: true,
+                });
+                break;
+            case 'oauth2':
+                rows.push({
+                    name: 'authorization',
+                    value: `Bearer ${redact ? GRPC_COMMAND_REDACTED : input.auth.accessToken}`,
+                    enabled: true,
+                });
+                break;
+            case 'api-key':
+                rows.push({
+                    name: input.auth.name.toLowerCase(),
+                    value: redact ? GRPC_COMMAND_REDACTED : input.auth.value,
+                    enabled: true,
+                });
+                break;
+            case 'basic':
+                rows.push({
+                    name: 'authorization',
+                    value: `Basic ${redact ? GRPC_COMMAND_REDACTED : Buffer.from(`${input.auth.username}:${input.auth.password}`).toString('base64')}`,
+                    enabled: true,
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    for (const row of input.metadata) {
+        if (row.enabled && row.name.trim() !== '') {
+            const name = row.name.trim().toLowerCase();
+            rows.push({ name, value: redact && SECRET_HEADERS.has(name) ? GRPC_COMMAND_REDACTED : row.value, enabled: true });
+        }
+    }
+    return rows;
+}
+/**
+ * Renders one call as a shell command. `messageText` is the request JSON, one object or an array,
+ * passed as the data argument; a client stream is what an array means to such a tool as well.
+ */
+export function grpcToCommand(input, messageText, options = {}) {
+    const shell = options.shell ?? 'posix';
+    const q = (value) => quoteForShell(value, shell);
+    const parts = ['grpcurl'];
+    if (!input.tls) {
+        parts.push('-plaintext');
+    }
+    if (options.importPath !== undefined) {
+        parts.push('-import-path', q(options.importPath));
+    }
+    for (const file of options.protoFiles ?? []) {
+        parts.push('-proto', q(file));
+    }
+    parts.push('-max-time', String(Math.max(1, Math.ceil(input.timeoutMs / 1000))));
+    for (const row of headerRows(input, options.redactSecrets !== false)) {
+        parts.push('-H', q(`${row.name}: ${row.value}`));
+    }
+    const compact = messageText.trim() === '' ? '{}' : messageText.trim();
+    parts.push('-d', q(compact));
+    parts.push(q(input.target), q(`${input.service}/${input.method}`));
+    // One option per line, its value on the same line, so the command reads top to bottom.
+    const continuation = shell === 'powershell' ? ' `\n  ' : ' \\\n  ';
+    let out = parts[0] ?? '';
+    for (let index = 1; index < parts.length; index += 1) {
+        const part = parts[index];
+        out += part.startsWith('-') || index === parts.length - 2 ? `${continuation}${part}` : ` ${part}`;
+    }
+    return out;
+}

package/dist/grpc/expand.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Property expansion for a gRPC call: every `${…}` reference in the target, the metadata rows and
+ * the message text, resolved against the same scopes a SOAP or REST send uses. The rules are the
+ * REST ones: names as well as values are expanded, an unresolved reference is reported rather than
+ * guessed at, and escaping — JSON string escaping, when the request asks for it — applies to the
+ * message alone, never to a header or the target.
+ */
+import type { PropertyScopes, UnresolvedRef } from '../project/properties.js';
+import type { KeyValueEntry } from '../rest/model.js';
+/** The parts of a call that carry text a property can appear in. */
+export interface GrpcExpandable {
+    readonly target: string;
+    readonly metadata: readonly KeyValueEntry[];
+    readonly messageText: string;
+}
+/** Options for {@link expandGrpcInput}. */
+export interface ExpandGrpcOptions {
+    /** JSON-escape every value substituted into the message text: the request's *escape properties* setting. */
+    readonly escape?: boolean;
+}
+/** Expands every property reference in a call's target, metadata and message text. */
+export declare function expandGrpcInput<T extends GrpcExpandable>(input: T, scopes: PropertyScopes, options?: ExpandGrpcOptions): {
+    readonly input: T;
+    readonly unresolved: UnresolvedRef[];
+};

package/dist/grpc/expand.js

@@ -0,0 +1,52 @@
+/**
+ * Property expansion for a gRPC call: every `${…}` reference in the target, the metadata rows and
+ * the message text, resolved against the same scopes a SOAP or REST send uses. The rules are the
+ * REST ones: names as well as values are expanded, an unresolved reference is reported rather than
+ * guessed at, and escaping — JSON string escaping, when the request asks for it — applies to the
+ * message alone, never to a header or the target.
+ */
+import { expand } from '../project/properties.js';
+import { escapeForLanguage } from '../rest/body.js';
+/** Expands every property reference in a call's target, metadata and message text. */
+export function expandGrpcInput(input, scopes, options = {}) {
+    const unresolved = [];
+    const run = (text) => {
+        const result = expand(text, scopes);
+        unresolved.push(...result.unresolved);
+        return result.text;
+    };
+    const runMessage = (text) => {
+        const result = expand(text, scopes);
+        unresolved.push(...result.unresolved);
+        return options.escape === true ? expand(text, escapedScopes(scopes)).text : result.text;
+    };
+    return {
+        input: {
+            ...input,
+            target: run(input.target),
+            metadata: input.metadata.map((row) => ({ ...row, name: run(row.name), value: run(row.value) })),
+            messageText: runMessage(input.messageText),
+        },
+        unresolved,
+    };
+}
+/** The same scopes with every value JSON-escaped, so substitution escapes as it goes. */
+function escapedScopes(scopes) {
+    const escapeMap = (map) => {
+        const out = {};
+        for (const [name, value] of Object.entries(map ?? {})) {
+            if (value !== undefined) {
+                out[name] = escapeForLanguage(value, 'json');
+            }
+        }
+        return out;
+    };
+    return {
+        ...scopes,
+        project: escapeMap(scopes.project),
+        global: escapeMap(scopes.global),
+        system: escapeMap(scopes.system),
+        ...(scopes.env !== undefined ? { env: escapeMap(scopes.env) } : {}),
+        ...(scopes.workspace !== undefined ? { workspace: escapeMap(scopes.workspace) } : {}),
+    };
+}

package/dist/grpc/framing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The length-prefixed message framing gRPC lays over an HTTP/2 stream: every message is one byte
+ * of flags (bit 0: compressed) and a four-byte big-endian length, then the payload. Pure byte
+ * work with no I/O, so it is unit-tested against arrays.
+ */
+/** One frame as parsed off the stream. */
+export interface GrpcFrame {
+    readonly compressed: boolean;
+    readonly payload: Uint8Array;
+}
+/** Encodes one message as a gRPC frame. */
+export declare function encodeGrpcFrame(payload: Uint8Array, compressed?: boolean): Uint8Array;
+/**
+ * Reassembles frames from the DATA chunks of an HTTP/2 stream, which split and join messages
+ * however the transport pleases. Feed each chunk to {@link push}; each call returns the frames
+ * completed by it. Call {@link finish} at end of stream to learn whether bytes were left over.
+ */
+export declare class GrpcFrameParser {
+    private buffered;
+    private readonly maxMessageBytes;
+    constructor(options?: {
+        readonly maxMessageBytes?: number;
+    });
+    /** Appends a chunk and returns the frames it completed, in order. */
+    push(chunk: Uint8Array): GrpcFrame[];
+    /** Bytes received but not forming a whole frame — non-zero at end of stream means a truncated message. */
+    get pending(): number;
+}

package/dist/grpc/framing.js

@@ -0,0 +1,61 @@
+/**
+ * The length-prefixed message framing gRPC lays over an HTTP/2 stream: every message is one byte
+ * of flags (bit 0: compressed) and a four-byte big-endian length, then the payload. Pure byte
+ * work with no I/O, so it is unit-tested against arrays.
+ */
+import { GrpcError } from '../errors.js';
+const HEADER_BYTES = 5;
+/** Encodes one message as a gRPC frame. */
+export function encodeGrpcFrame(payload, compressed = false) {
+    const frame = new Uint8Array(HEADER_BYTES + payload.byteLength);
+    frame[0] = compressed ? 1 : 0;
+    new DataView(frame.buffer).setUint32(1, payload.byteLength, false);
+    frame.set(payload, HEADER_BYTES);
+    return frame;
+}
+/**
+ * Reassembles frames from the DATA chunks of an HTTP/2 stream, which split and join messages
+ * however the transport pleases. Feed each chunk to {@link push}; each call returns the frames
+ * completed by it. Call {@link finish} at end of stream to learn whether bytes were left over.
+ */
+export class GrpcFrameParser {
+    buffered = new Uint8Array(0);
+    maxMessageBytes;
+    constructor(options) {
+        this.maxMessageBytes = options?.maxMessageBytes ?? 64 * 1024 * 1024;
+    }
+    /** Appends a chunk and returns the frames it completed, in order. */
+    push(chunk) {
+        if (this.buffered.byteLength === 0) {
+            this.buffered = chunk;
+        }
+        else {
+            const joined = new Uint8Array(this.buffered.byteLength + chunk.byteLength);
+            joined.set(this.buffered, 0);
+            joined.set(chunk, this.buffered.byteLength);
+            this.buffered = joined;
+        }
+        const frames = [];
+        let offset = 0;
+        while (this.buffered.byteLength - offset >= HEADER_BYTES) {
+            const view = new DataView(this.buffered.buffer, this.buffered.byteOffset + offset, HEADER_BYTES);
+            const flags = view.getUint8(0);
+            const length = view.getUint32(1, false);
+            if (length > this.maxMessageBytes) {
+                throw new GrpcError('grpc-message-too-large', `A message of ${String(length)} bytes exceeds the ${String(this.maxMessageBytes)}-byte limit`, { details: { length, max: this.maxMessageBytes } });
+            }
+            if (this.buffered.byteLength - offset - HEADER_BYTES < length) {
+                break;
+            }
+            const start = offset + HEADER_BYTES;
+            frames.push({ compressed: (flags & 1) === 1, payload: this.buffered.slice(start, start + length) });
+            offset = start + length;
+        }
+        this.buffered = offset === 0 ? this.buffered : this.buffered.slice(offset);
+        return frames;
+    }
+    /** Bytes received but not forming a whole frame — non-zero at end of stream means a truncated message. */
+    get pending() {
+        return this.buffered.byteLength;
+    }
+}

package/dist/grpc/import.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Turning a `.proto` set into a gRPC API: a folder per service and a request per method, each
+ * request seeded with a sample message — the shape an OpenAPI import produces, and the shape the
+ * REST spec's §8 asked a gRPC import to reproduce. Pure: the caller reads the files and, when it
+ * wants a cache, writes one with `cache.ts`.
+ */
+import type { IdGenerator } from '../project/model.js';
+import type { GrpcApi, GrpcDefinitionRef } from './model.js';
+import type { GrpcServiceDescriptor } from './proto/describe.js';
+import type { ProtoSet, ProtoSources } from './proto/load.js';
+/** Options for {@link importProto}. */
+export interface ImportProtoOptions {
+    /** The files to start from; defaults to every source. */
+    readonly roots?: readonly string[];
+    /** The API's name. Defaults to the first service's package, or its name when it has none. */
+    readonly name?: string;
+    readonly target?: string;
+    readonly tls?: boolean;
+    readonly definition?: GrpcDefinitionRef;
+    readonly newId?: IdGenerator;
+    readonly order?: number;
+}
+/** What an import produced, in numbers, for the summary step. */
+export interface ProtoImportSummary {
+    readonly files: number;
+    readonly services: number;
+    readonly methods: number;
+    readonly deprecated: number;
+}
+/** The result of {@link importProto}. */
+export interface ImportedProto {
+    readonly api: GrpcApi;
+    readonly set: ProtoSet;
+    readonly services: readonly GrpcServiceDescriptor[];
+    readonly summary: ProtoImportSummary;
+}
+/**
+ * Builds a gRPC API from an already-loaded set: a folder per service (named by its short name, the
+ * package in the description when there is one), a request per method.
+ */
+export declare function apiFromProtoSet(set: ProtoSet, options?: ImportProtoOptions): ImportedProto;
+/**
+ * Loads `sources` and builds an API from them.
+ *
+ * @throws ProtoError as {@link loadProtoSet} does
+ */
+export declare function importProto(sources: ProtoSources, options?: ImportProtoOptions): ImportedProto;

package/dist/grpc/import.js

@@ -0,0 +1,88 @@
+/**
+ * Turning a `.proto` set into a gRPC API: a folder per service and a request per method, each
+ * request seeded with a sample message — the shape an OpenAPI import produces, and the shape the
+ * REST spec's §8 asked a gRPC import to reproduce. Pure: the caller reads the files and, when it
+ * wants a cache, writes one with `cache.ts`.
+ */
+import { uniqueSlug } from '../project/paths.js';
+import { createGrpcApi, createGrpcFolder, createGrpcRequest } from './model.js';
+import { describeServices } from './proto/describe.js';
+import { loadProtoSet } from './proto/load.js';
+import { sampleMessageText } from './proto/sample.js';
+/** A method's description: its leading comment, with a deprecation notice ahead of it. */
+function requestDescription(method) {
+    const parts = [method.deprecated === true ? '**Deprecated.**' : undefined, method.comment].filter((part) => part !== undefined && part !== '');
+    return parts.length > 0 ? parts.join(' ') : undefined;
+}
+/** One request per method, slugs unique within the folder. */
+function requestsFor(set, service, options) {
+    const taken = new Set();
+    return service.methods.map((method, index) => {
+        const slug = uniqueSlug(method.name, taken);
+        taken.add(slug.toLowerCase());
+        const description = requestDescription(method);
+        return createGrpcRequest(method.name, {
+            slug,
+            order: index,
+            ...(options.newId !== undefined ? { newId: options.newId } : {}),
+            ...(description !== undefined ? { description } : {}),
+            service: service.fullName,
+            method: method.name,
+            methodKind: method.kind,
+            message: sampleMessageText(set, method.requestType),
+        });
+    });
+}
+/**
+ * Builds a gRPC API from an already-loaded set: a folder per service (named by its short name, the
+ * package in the description when there is one), a request per method.
+ */
+export function apiFromProtoSet(set, options = {}) {
+    const services = describeServices(set);
+    const folderSlugs = new Set();
+    const folders = services.map((service, index) => {
+        const slug = uniqueSlug(service.name, folderSlugs);
+        folderSlugs.add(slug.toLowerCase());
+        const description = [service.package !== '' ? `Package \`${service.package}\`.` : undefined, service.comment]
+            .filter((part) => part !== undefined && part !== '')
+            .join(' ');
+        return createGrpcFolder(service.name, {
+            slug,
+            order: index,
+            ...(options.newId !== undefined ? { newId: options.newId } : {}),
+            ...(description !== '' ? { description } : {}),
+            requests: requestsFor(set, service, options),
+        });
+    });
+    const first = services[0];
+    const name = options.name ?? (first === undefined ? 'gRPC API' : first.package !== '' ? first.package : first.name);
+    const api = createGrpcApi(name, {
+        ...(options.newId !== undefined ? { newId: options.newId } : {}),
+        ...(options.order !== undefined ? { order: options.order } : {}),
+        ...(options.target !== undefined ? { target: options.target } : {}),
+        ...(options.tls !== undefined ? { tls: options.tls } : {}),
+        ...(options.definition !== undefined ? { definition: options.definition } : {}),
+        folders,
+    });
+    const methods = services.flatMap((service) => service.methods);
+    return {
+        api,
+        set,
+        services,
+        summary: {
+            files: set.files.length,
+            services: services.length,
+            methods: methods.length,
+            deprecated: methods.filter((method) => method.deprecated === true).length,
+        },
+    };
+}
+/**
+ * Loads `sources` and builds an API from them.
+ *
+ * @throws ProtoError as {@link loadProtoSet} does
+ */
+export function importProto(sources, options = {}) {
+    const set = loadProtoSet(sources, options.roots !== undefined ? { roots: options.roots } : {});
+    return apiFromProtoSet(set, options);
+}

package/dist/grpc/model.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The gRPC third of the project model: a *gRPC API* — a target, a set of `.proto` files, and a
+ * tree of folders and requests, one request per method call the user wants to keep.
+ *
+ * A gRPC API is the third sibling container beside a SOAP interface and a REST API (ADR-0007). It
+ * lives in the same `apis/<slug>/` directory a REST API does and identifies itself with
+ * `kind: grpc` at the top of every file it writes, so a file says what it is without anyone having
+ * to know which directory implies which protocol. In memory it is kept in its own list on the
+ * project so the compiler points at every surface that needs a third branch rather than letting a
+ * gRPC API fall through a REST-shaped `if`.
+ *
+ * The same rules as the other two models apply: every field is `readonly`, ids are ULIDs so an
+ * entity survives a rename, `slug` is the file-system name derived from `name`, and nothing here
+ * ever holds a secret — credentials are `secretRef`s resolved from the OS keychain at send time.
+ */
+import type { AuthConfig, CreateOptions, IdGenerator } from '../project/model.js';
+import type { KeyValueEntry } from '../rest/model.js';
+import type { GrpcMethodKind, GrpcReflectionVersion } from './shape.js';
+export { clientStreams, defaultTlsFor, GRPC_REFLECTION_VERSIONS, grpcMethodPath, serverStreams } from './shape.js';
+export type { GrpcMethodKind, GrpcReflectionVersion } from './shape.js';
+/**
+ * Per-request transport settings. Every field is optional and an absent one means *inherit*, not
+ * *off*: the send resolves request → API → project → preference, exactly as a REST request does.
+ */
+export interface GrpcRequestSettings {
+    /** The call deadline, sent as `grpc-timeout` and enforced locally. */
+    readonly timeoutMs?: number;
+    /** Send even when the server's certificate does not verify; badged in red wherever it appears. */
+    readonly trustInvalid?: boolean;
+    /** Id of a `wss/keystores.yaml` entry: the client identity this request's TLS handshake presents. */
+    readonly sslKeystoreRef?: string;
+    readonly bindAddress?: string;
+    /** Stop reading the response once this many message bytes have arrived. */
+    readonly maxSizeBytes?: number;
+    /** JSON-escape every property value substituted into the message text. Off by default. */
+    readonly escapeProperties?: boolean;
+}
+/** A saved gRPC request: everything but the message text lives in `<slug>.request.yaml`. */
+export interface GrpcRequestDef {
+    readonly kind: 'grpc';
+    readonly id: string;
+    readonly name: string;
+    /** File-system name (without the `.request.yaml` suffix). */
+    readonly slug: string;
+    readonly order: number;
+    /** Markdown, shown in the Details inspector; imported from the method's leading comment. */
+    readonly description?: string;
+    /** The fully qualified service name, e.g. `helloworld.Greeter`. */
+    readonly service: string;
+    /** The method's own name, e.g. `SayHello`. */
+    readonly method: string;
+    readonly methodKind: GrpcMethodKind;
+    /** Metadata sent with the call, one row per key. Names are lower-cased on the wire. */
+    readonly metadata: readonly KeyValueEntry[];
+    /**
+     * The request message as JSON text, exactly as edited, stored in the sibling `<slug>.body.json`.
+     * One object for a unary or server-streaming call; a JSON array of objects for a client- or
+     * bidirectional-streaming call, sent in order before the stream is closed.
+     */
+    readonly message: string;
+    /** `inherit` by default: the folder chain, then the API, decides. */
+    readonly auth: AuthConfig;
+    readonly settings: GrpcRequestSettings;
+    /**
+     * True when the method this request was made from is no longer in the API's definition. Nothing
+     * is deleted on a re-import; the request survives badged, as a SOAP request does.
+     */
+    readonly orphaned?: boolean;
+}
+/** A named node in a gRPC API's tree. An import makes one per service. */
+export interface GrpcFolder {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    /** Default credentials for everything inside, unless a child says otherwise. */
+    readonly auth?: AuthConfig;
+    readonly folders: readonly GrpcFolder[];
+    readonly requests: readonly GrpcRequestDef[];
+}
+/**
+ * Where an API's schema came from, cached under `apis/<slug>/definition/`.
+ *
+ * `proto` is an import of `.proto` files, cached byte-exact at their import paths. `reflection` is a
+ * server that described itself, cached as the descriptor set it sent. A project written before
+ * reflection existed has no `kind`, and reads as `proto`.
+ */
+export interface GrpcDefinitionRef {
+    /** How the definition was obtained. */
+    readonly kind: 'proto' | 'reflection';
+    /** Where it came from: a target for reflection, a URL or a path as the user gave it for an import. */
+    readonly source: string;
+    readonly cache: boolean;
+    /**
+     * For an import, the import paths of the files it started from. For reflection, the names of the
+     * descriptor files declaring the services.
+     */
+    readonly roots: readonly string[];
+    /** For a reflection definition, the version to ask with when it is refreshed. Absent means `auto`. */
+    readonly reflectionVersion?: GrpcReflectionVersion;
+    /**
+     * For a reflection definition, ask again even when the server's certificate does not verify —
+     * remembered from the discovery so a refresh reaches the same development server it did.
+     */
+    readonly trustInvalid?: boolean;
+}
+/** A gRPC API: a `host:port` target, whether to speak TLS to it, and a tree of folders and requests. */
+export interface GrpcApi {
+    readonly kind: 'grpc';
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    /** Position among the project's interfaces, REST APIs and gRPC APIs, which share one ordering space. */
+    readonly order: number;
+    readonly description?: string;
+    /**
+     * The server to call, as `host:port` (or a `grpc://` / `grpcs://` / `http(s)://` URL, whose scheme
+     * decides TLS). May contain `${…}` properties; an environment can override it per environment
+     * under the same key a REST base URL uses.
+     */
+    readonly target: string;
+    /** Speak TLS to the target. Off means plaintext HTTP/2 (`h2c`), what a local development server speaks. */
+    readonly tls: boolean;
+    /** Metadata every request under this API sends unless it sets the same key itself. */
+    readonly metadata: readonly KeyValueEntry[];
+    readonly auth?: AuthConfig;
+    readonly definition?: GrpcDefinitionRef;
+    readonly folders: readonly GrpcFolder[];
+    readonly requests: readonly GrpcRequestDef[];
+}
+/** Input to {@link createGrpcApi} beyond the name. */
+export interface CreateGrpcApiInput extends CreateOptions {
+    readonly target?: string;
+    readonly tls?: boolean;
+    readonly slug?: string;
+    readonly description?: string;
+    readonly metadata?: readonly KeyValueEntry[];
+    readonly auth?: AuthConfig;
+    readonly definition?: GrpcDefinitionRef;
+    readonly folders?: readonly GrpcFolder[];
+    readonly requests?: readonly GrpcRequestDef[];
+}
+/**
+ * Creates an empty gRPC API. TLS defaults from the target: on for a `grpcs://`/`https://` URL or a
+ * `:443` port, otherwise off, since a bare `localhost:50051` is what a development server offers.
+ */
+export declare function createGrpcApi(name: string, input?: CreateGrpcApiInput): GrpcApi;
+/** Input to {@link createGrpcFolder} beyond the name. */
+export interface CreateGrpcFolderInput extends CreateOptions {
+    readonly slug?: string;
+    readonly description?: string;
+    readonly auth?: AuthConfig;
+    readonly folders?: readonly GrpcFolder[];
+    readonly requests?: readonly GrpcRequestDef[];
+}
+/** Creates an empty folder. */
+export declare function createGrpcFolder(name: string, input?: CreateGrpcFolderInput): GrpcFolder;
+/** Input to {@link createGrpcRequest} beyond the name. */
+export interface CreateGrpcRequestInput extends CreateOptions {
+    readonly service?: string;
+    readonly method?: string;
+    readonly methodKind?: GrpcMethodKind;
+    readonly slug?: string;
+    readonly description?: string;
+    readonly metadata?: readonly KeyValueEntry[];
+    readonly message?: string;
+    readonly auth?: AuthConfig;
+    readonly settings?: GrpcRequestSettings;
+}
+/** Creates a unary request with an empty message and inherited credentials. */
+export declare function createGrpcRequest(name: string, input?: CreateGrpcRequestInput): GrpcRequestDef;
+export type { IdGenerator };
+/** Every request in `folder` and, depth-first, in the folders below it. */
+export declare function grpcFolderRequests(folder: Pick<GrpcFolder, 'folders' | 'requests'>): GrpcRequestDef[];
+/** Every request in `api`, its root requests first and then each folder depth-first. */
+export declare function grpcApiRequests(api: GrpcApi): GrpcRequestDef[];
+/** Every folder in `api`, depth-first. */
+export declare function grpcApiFolders(api: GrpcApi): GrpcFolder[];

package/dist/grpc/model.js

@@ -0,0 +1,91 @@
+/**
+ * The gRPC third of the project model: a *gRPC API* — a target, a set of `.proto` files, and a
+ * tree of folders and requests, one request per method call the user wants to keep.
+ *
+ * A gRPC API is the third sibling container beside a SOAP interface and a REST API (ADR-0007). It
+ * lives in the same `apis/<slug>/` directory a REST API does and identifies itself with
+ * `kind: grpc` at the top of every file it writes, so a file says what it is without anyone having
+ * to know which directory implies which protocol. In memory it is kept in its own list on the
+ * project so the compiler points at every surface that needs a third branch rather than letting a
+ * gRPC API fall through a REST-shaped `if`.
+ *
+ * The same rules as the other two models apply: every field is `readonly`, ids are ULIDs so an
+ * entity survives a rename, `slug` is the file-system name derived from `name`, and nothing here
+ * ever holds a secret — credentials are `secretRef`s resolved from the OS keychain at send time.
+ */
+import { generateId } from '../project/model.js';
+import { slugify } from '../project/paths.js';
+import { defaultTlsFor } from './shape.js';
+// The pure shape rules live in `shape.ts`, which imports nothing, so the renderer can have them
+// without `node:path` coming along; they are re-exported here because this is where callers expect
+// a gRPC model rule to be.
+export { clientStreams, defaultTlsFor, GRPC_REFLECTION_VERSIONS, grpcMethodPath, serverStreams } from './shape.js';
+function idOf(options) {
+    return options?.id ?? (options?.newId ?? generateId)();
+}
+/**
+ * Creates an empty gRPC API. TLS defaults from the target: on for a `grpcs://`/`https://` URL or a
+ * `:443` port, otherwise off, since a bare `localhost:50051` is what a development server offers.
+ */
+export function createGrpcApi(name, input = {}) {
+    const target = input.target ?? '';
+    return {
+        kind: 'grpc',
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        target,
+        tls: input.tls ?? defaultTlsFor(target),
+        metadata: input.metadata ?? [],
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        ...(input.definition !== undefined ? { definition: input.definition } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates an empty folder. */
+export function createGrpcFolder(name, input = {}) {
+    return {
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates a unary request with an empty message and inherited credentials. */
+export function createGrpcRequest(name, input = {}) {
+    return {
+        kind: 'grpc',
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        service: input.service ?? '',
+        method: input.method ?? '',
+        methodKind: input.methodKind ?? 'unary',
+        metadata: input.metadata ?? [],
+        message: input.message ?? '{}',
+        auth: input.auth ?? { type: 'inherit' },
+        settings: input.settings ?? {},
+    };
+}
+/** Every request in `folder` and, depth-first, in the folders below it. */
+export function grpcFolderRequests(folder) {
+    return [...folder.requests, ...folder.folders.flatMap((child) => grpcFolderRequests(child))];
+}
+/** Every request in `api`, its root requests first and then each folder depth-first. */
+export function grpcApiRequests(api) {
+    return grpcFolderRequests(api);
+}
+/** Every folder in `api`, depth-first. */
+export function grpcApiFolders(api) {
+    const walk = (folders) => folders.flatMap((folder) => [folder, ...walk(folder.folders)]);
+    return walk(api.folders);
+}