google-apis-cli 0.1.0 → 0.3.0

package/dist/src/plan.js

@@ -0,0 +1,348 @@
+// Planner: command words + parsed --params/--body → one validated CallPlan (epic #30 D4, D5).
+// Pure: no I/O; every rejection is a GapiError thrown before any network call.
+import { extname } from 'node:path';
+import { GapiError, messageOf } from './errors.js';
+import { isRecord } from './json.js';
+// Document-level parameters gapi sets itself (D5).
+const OWNED = new Set([
+    'alt',
+    'key',
+    'access_token',
+    'oauth_token',
+    'callback',
+    'prettyPrint',
+    'uploadType',
+    'upload_protocol',
+    '$.xgafv',
+]);
+// gaxios httpMethodsToRetry, without OPTIONS: a resend of these changes nothing more.
+const IDEMPOTENT = new Set(['GET', 'HEAD', 'PUT', 'DELETE']);
+// The document-level parameters a caller may pass (D5).
+const SHARED = ['fields', 'quotaUser'];
+const PROTOCOLS = ['media', 'multipart', 'resumable'];
+// --upload-content-type default by file extension (D7); anything else is octet-stream.
+const CONTENT_TYPES = new Map([
+    ['.png', 'image/png'],
+    ['.jpg', 'image/jpeg'],
+    ['.jpeg', 'image/jpeg'],
+    ['.gif', 'image/gif'],
+    ['.webp', 'image/webp'],
+    ['.mp4', 'video/mp4'],
+    ['.mov', 'video/quicktime'],
+    ['.webm', 'video/webm'],
+    ['.csv', 'text/csv'],
+    ['.txt', 'text/plain'],
+    ['.json', 'application/json'],
+    ['.pdf', 'application/pdf'],
+    ['.zip', 'application/zip'],
+]);
+const invalid = (message) => new GapiError(3, message);
+// Walk the resources tree by exact key; a method key must be the last word.
+export function resolve(model, words) {
+    let node = model;
+    for (const [i, word] of words.entries()) {
+        const method = node.methods.get(word);
+        if (method) {
+            if (i < words.length - 1)
+                throw invalid(`unexpected argument '${words[i + 1]}'`);
+            return { method };
+        }
+        const next = node.resources.get(word);
+        if (!next) {
+            const kind = node.methods.size === 0
+                ? 'resource'
+                : node.resources.size === 0
+                    ? 'method'
+                    : 'resource or method';
+            const valid = [...node.resources.keys(), ...node.methods.keys()].join(', ');
+            throw invalid(`unknown ${kind} '${word}' (valid: ${valid})`);
+        }
+        node = next;
+    }
+    return { node };
+}
+export function plan(model, target, input, settings) {
+    const method = typeof target === 'string' ? model.byId.get(target) : resolve(model, target).method;
+    if (!method)
+        throw invalid(`not a method: ${typeof target === 'string' ? target : target.join(' ')}`);
+    const command = `${model.api} ${method.words.join(' ')}`;
+    if (method.retired)
+        throw invalid(`retired: ${method.retired.reason} (${method.retired.source})`);
+    if (method.unavailable && !input.dryRun) {
+        throw new GapiError(2, `${command}: unavailable: scope not grantable`);
+    }
+    const warnings = method.deprecated
+        ? [
+            `${command} is deprecated${method.deprecated.source ? ` (${method.deprecated.source})` : ''}`,
+        ]
+        : [];
+    const values = paramValues(model, method, input.params ?? {});
+    if (input.body !== undefined && !method.request)
+        throw invalid(`--body: ${command} takes no request body`);
+    const mode = sendMode(method, command, input);
+    const body = mode.send === 'pages' && mode.paging === 'body' ? mode.body : input.body;
+    const url = buildUrl(model, method, values, mode);
+    const headers = contentHeaders(mode, body !== undefined);
+    if (model.auth === 'oauth' && settings.project)
+        headers['x-goog-user-project'] = settings.project;
+    Object.assign(headers, settings.headers);
+    return {
+        methodId: method.id,
+        httpMethod: method.httpMethod,
+        url,
+        headers,
+        body,
+        auth: { kind: model.auth, scopes: method.scopes },
+        warnings,
+        ...(IDEMPOTENT.has(method.httpMethod) || method.read ? { retry: true } : {}),
+        ...mode,
+    };
+}
+// The outer CallPlan of a batch call: one POST to the document's `batchPath` endpoint that
+// carries `parts`, each planned by `plan` with its own headers (D7).
+export function batchPlan(model, parts) {
+    const [first] = parts;
+    return {
+        methodId: first.methodId,
+        httpMethod: 'POST',
+        url: `${model.rootUrl}${model.batchPath}`,
+        headers: {},
+        auth: first.auth,
+        warnings: first.warnings,
+        send: 'batch',
+        parts,
+    };
+}
+// JSON for a body, the file type for a media upload; Transport adds the multipart boundary.
+function contentHeaders(mode, hasBody) {
+    const json = hasBody ? { 'Content-Type': 'application/json' } : {};
+    if (mode.send !== 'upload')
+        return json;
+    const { protocol, contentType } = mode.upload;
+    if (protocol === 'media')
+        return { 'Content-Type': contentType };
+    if (protocol === 'multipart')
+        return {};
+    return { ...json, 'X-Upload-Content-Type': contentType };
+}
+// D6 paging, D7 media: at most one of --page-all, --upload, --output, each only where the
+// method supports it.
+function sendMode(method, command, input) {
+    const chosen = [
+        input.pageAll && '--page-all',
+        input.upload !== undefined && '--upload',
+        input.output !== undefined && '--output',
+    ].filter((flag) => typeof flag === 'string');
+    if (chosen.length > 1)
+        throw invalid(`${chosen[0]} and ${chosen[1]} cannot be combined`);
+    if (input.pageLimit !== undefined && !input.pageAll) {
+        throw invalid('--page-limit needs --page-all');
+    }
+    if (input.upload !== undefined) {
+        const hasBody = input.body !== undefined;
+        return { send: 'upload', upload: upload(method, command, input.upload, input, hasBody) };
+    }
+    for (const [flag, value] of [
+        ['--upload-content-type', input.uploadContentType],
+        ['--upload-protocol', input.uploadProtocol],
+    ]) {
+        if (value !== undefined)
+            throw invalid(`${flag} needs --upload`);
+    }
+    if (input.output !== undefined) {
+        if (!method.download)
+            throw invalid(`--output: ${command} has no media download`);
+        return { send: 'download', output: input.output };
+    }
+    if (!input.pageAll)
+        return { send: 'once' };
+    if (!method.paging) {
+        throw invalid(`--page-all: ${command} has no pageToken parameter or request field`);
+    }
+    const limit = input.pageLimit ?? '10';
+    if (!/^[1-9]\d*$/.test(limit))
+        throw invalid('--page-limit must be a positive integer');
+    const pageLimit = Number(limit);
+    if (method.paging === 'query')
+        return { send: 'pages', pageLimit, paging: 'query' };
+    // Body paging: every page sends this object, from page 2 on with pageToken set (D6).
+    const body = input.body ?? {};
+    if (!isRecord(body))
+        throw invalid('--page-all: --body must be a JSON object');
+    return { send: 'pages', pageLimit, paging: 'body', body };
+}
+// D7: protocol defaults to multipart with --body, else media; the type must fit `accept`.
+function upload(method, command, path, input, hasBody) {
+    if (!method.upload)
+        throw invalid(`--upload: ${command} takes no media upload`);
+    const protocol = input.uploadProtocol ?? (hasBody ? 'multipart' : 'media');
+    if (!isProtocol(protocol)) {
+        throw invalid(`--upload-protocol must be one of: ${PROTOCOLS.join(', ')}`);
+    }
+    if (protocol === 'resumable' && !method.upload.resumable) {
+        throw invalid(`--upload-protocol resumable: ${command} has no resumable upload`);
+    }
+    // An explicit protocol that would drop or lack the --body metadata.
+    if (protocol === 'multipart' && !hasBody) {
+        throw invalid('--upload-protocol multipart needs --body');
+    }
+    if (protocol === 'media' && hasBody)
+        throw invalid('--upload-protocol media takes no --body');
+    const contentType = input.uploadContentType ??
+        CONTENT_TYPES.get(extname(path).toLowerCase()) ??
+        'application/octet-stream';
+    const { accept } = method.upload;
+    if (accept.length > 0 && !accept.some((pattern) => accepts(pattern, contentType))) {
+        throw invalid(`--upload-content-type ${contentType}: ${command} accepts ${accept.join(', ')}`);
+    }
+    return { path, contentType, protocol };
+}
+const isProtocol = (p) => PROTOCOLS.includes(p);
+// A discovery `accept` pattern: `*/*`, `<type>/*` or an exact type; MIME types ignore case.
+function accepts(pattern, contentType) {
+    const p = pattern.toLowerCase();
+    const t = contentType.split(';')[0].trim().toLowerCase();
+    return p === '*/*' || p === t || (p.endsWith('/*') && t.startsWith(p.slice(0, -1)));
+}
+// argv JSON for --params / --body; invalid JSON and unsafe integers exit 3.
+export function parseJson(flag, text) {
+    if (text === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (e) {
+        throw invalid(`${flag} is not valid JSON: ${messageOf(e)}`);
+    }
+    const path = unsafeInteger(value, '');
+    if (path !== undefined) {
+        throw invalid(`${flag}${path && ` ${path}`}: integer exceeds 2^53; pass it as a string`);
+    }
+    return value;
+}
+// JSON.parse rounds integers past 2^53; Discovery sends int64 as a string (discovery/v1/type-format).
+function unsafeInteger(value, path) {
+    if (typeof value === 'number') {
+        return Math.abs(value) > Number.MAX_SAFE_INTEGER ? path : undefined;
+    }
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const array = Array.isArray(value);
+    for (const [key, item] of Object.entries(value)) {
+        const found = unsafeInteger(item, array ? `${path}[${key}]` : path ? `${path}.${key}` : key);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+// --params → one list of string values per known parameter (D5 value rules).
+function paramValues(model, method, params) {
+    if (typeof params !== 'object' || params === null || Array.isArray(params)) {
+        throw invalid('--params must be a JSON object');
+    }
+    const shared = SHARED.filter((k) => model.parameters.has(k));
+    const out = new Map();
+    for (const [name, raw] of Object.entries(params)) {
+        const spec = method.parameters.get(name) ??
+            (shared.includes(name) ? model.parameters.get(name) : undefined);
+        if (!spec) {
+            if (OWNED.has(name))
+                throw invalid(`${name} is set by gapi`);
+            const valid = [...method.parameters.keys(), ...shared].join(', ');
+            throw invalid(`unknown param ${name} (valid: ${valid})`);
+        }
+        if (Array.isArray(raw) && !spec.repeated)
+            throw invalid(`${name} takes one value, not an array`);
+        const values = (Array.isArray(raw) ? raw : [raw]).map((v) => {
+            if (typeof v === 'string')
+                return v;
+            if (typeof v === 'number' || typeof v === 'boolean')
+                return String(v);
+            throw invalid(`${name} must be a string, number or boolean`);
+        });
+        // An empty list or a required '' sends nothing; a path would lose its segment.
+        if (values.length === 0)
+            throw invalid(`${name} needs at least one value`);
+        if (spec.required && values.includes(''))
+            throw invalid(`${name} needs a value`);
+        for (const v of values) {
+            if (spec.enum && !spec.enum.includes(v)) {
+                throw invalid(`${name} must be one of: ${spec.enum.join(', ')}`);
+            }
+            const type = spec.type === 'integer' || /int64$/.test(spec.format ?? '') ? 'integer' : spec.type;
+            if (type === 'integer' && !/^-?\d+$/.test(v))
+                throw invalid(`${name} must be an integer`);
+            if (type === 'boolean' && v !== 'true' && v !== 'false') {
+                throw invalid(`${name} must be true or false`);
+            }
+            // Path patterns are checked in buildUrl, after the bare-id hint (#28).
+            if (spec.location !== 'path' && spec.pattern && !matches(spec.pattern, v)) {
+                throw invalid(`${name} must match ${spec.pattern}`);
+            }
+        }
+        out.set(name, { spec, values });
+    }
+    for (const [name, spec] of method.parameters) {
+        if (spec.required && !out.has(name))
+            throw invalid(`missing required param ${name}`);
+    }
+    return out;
+}
+// rootUrl + servicePath + the discovery `path` with {x}/{+x} expanded, then the query string.
+// D7: an upload goes to rootUrl + `upload/` + …, a download adds alt=media and, on a
+// `useMediaDownloadService` method, goes to rootUrl + `download/` + … (Discovery "Using").
+function buildUrl(model, method, params, mode) {
+    const path = method.path.replace(/\{(\+?)([^}]+)\}/g, (_, reserved, name, offset) => {
+        const param = params.get(name);
+        if (!param)
+            throw invalid(`missing required param ${name}`);
+        const value = param.values[0];
+        if (param.spec.pattern && !matches(param.spec.pattern, value)) {
+            throw invalid(`${name} must match ${param.spec.pattern}`);
+        }
+        // googleapis-common validateAndEncodeParams: a `.`/`..` segment would make the URL
+        // parser leave the method path; `%2e` too, since WHATWG URL reads it as a dot.
+        const dot = (reserved ? value.split('/') : [value]).find((s) => /^(?:\.|%2e){1,2}$/i.test(s));
+        if (dot !== undefined)
+            throw invalid(`${name}: '${dot}' is a dot segment; pass a real id`);
+        if (reserved)
+            return value.split('/').map(encodeURIComponent).join('/');
+        // #28: `properties/{property}` + `properties/123` would encode to properties%2F123.
+        const segment = /[^/]+\/$/.exec(method.path.slice(0, offset))?.[0];
+        if (segment && value.startsWith(segment)) {
+            throw invalid(`pass the bare id: ${value.slice(segment.length)} (the path already has ${segment})`);
+        }
+        return encodeSegment(value);
+    });
+    const query = new URLSearchParams();
+    for (const [name, { spec, values }] of params) {
+        if (spec.location !== 'path')
+            for (const v of values)
+                query.append(name, v);
+    }
+    if (mode.send === 'upload')
+        query.append('uploadType', mode.upload.protocol);
+    if (mode.send === 'download')
+        query.append('alt', 'media');
+    const qs = query.toString();
+    const root = mode.send === 'upload'
+        ? `${model.rootUrl}upload/`
+        : mode.send === 'download' && method.download?.service
+            ? `${model.rootUrl}download/`
+            : model.rootUrl;
+    return `${root}${model.servicePath}${path}${qs ? `?${qs}` : ''}`;
+}
+// shortcut: a Java-only discovery pattern (e.g. `(?i)`) is skipped, not checked; translate
+// Java regex to JS if Google ever relies on one for a path.
+function matches(pattern, value) {
+    try {
+        return new RegExp(pattern).test(value);
+    }
+    catch {
+        return true;
+    }
+}
+// google/api/http.proto: {x} percent-encodes every character except [-_.~0-9a-zA-Z];
+// encodeURIComponent leaves !'()* as is.
+const encodeSegment = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);

package/dist/src/render.js

@@ -0,0 +1,248 @@
+// Renderers: plain text views over an ApiModel (epic #30 D4, story 8).
+import { isRecord } from './json.js';
+export const SCHEMA_USAGE = 'gapi schema <api> <resource>[.<sub-resource>…].<method> | <SchemaName> [--resolve-refs | --find <word>]';
+export const DISCOVERY_USAGE = 'gapi discovery refresh [<api>…] | path';
+export const AUTH_USAGE = 'gapi auth setup | login [--manual] | status | logout';
+export const SEARCH_USAGE = 'gapi search <words…>';
+const USAGE = `gapi <api> <resource> [<sub-resource>…] <method> [--params '<json>'] [--body '<json>']
+     [--upload <file> [--upload-content-type <type>] [--upload-protocol media|multipart|resumable]]
+     [--output <file>] [--page-all [--page-limit <n>]] [--cache <age>] [--dry-run]
+     [--project <id>] [--api-key <key>] [<entry header flags, e.g. ads --login-customer-id <id>>]
+gapi <api> [<resource>…]                  list sub-resources and methods
+gapi <api> <resource>… <method> --help    method help
+gapi <api> +<helper> … [--dry-run] [--cache <age>] [--project <id>] [--api-key <key>] [<entry header flags>]
+${SEARCH_USAGE}                      find methods by intent, max 20 hits
+${SCHEMA_USAGE}
+${DISCOVERY_USAGE}
+${AUTH_USAGE}
+`;
+export function rootHelp(apis) {
+    return `${USAGE}\napis:\n${apis
+        .toSorted()
+        .map((api) => `  ${api}\n`)
+        .join('')}`;
+}
+const markList = (m, { reasons = false } = {}) => [
+    m.deprecated && 'deprecated',
+    m.retired && (reasons ? `retired: ${m.retired.reason}` : 'retired'),
+    m.unavailable && 'unavailable: scope not grantable',
+    m.paid && (reasons ? `paid: ${m.paid.reason}` : 'paid'),
+].filter((s) => typeof s === 'string');
+const marks = (m) => markList(m)
+    .map((s) => ` (${s})`)
+    .join('');
+export function levelText(model, words, node, helpers = {}) {
+    const lines = [`gapi ${[model.api, ...words].join(' ')}`];
+    if (Object.keys(helpers).length > 0) {
+        lines.push('', 'helpers:', ...Object.entries(helpers).map(([k, h]) => `  ${k}  ${h.summary}`));
+    }
+    if (node.resources.size > 0) {
+        lines.push('', 'resources:', ...[...node.resources.keys()].map((k) => `  ${k}`));
+    }
+    if (node.methods.size > 0) {
+        lines.push('', 'methods:', ...[...node.methods].map(([k, m]) => `  ${k}${marks(m)}`));
+    }
+    return `${lines.join('\n')}\n`;
+}
+// Many documents state "Required." only in the description, not as `required: true`.
+const requiredFact = (p) => p.required
+    ? 'required'
+    : p.description?.startsWith('Required.')
+        ? 'required (per description)'
+        : undefined;
+export function methodHelp(model, m) {
+    const lines = [`gapi ${model.api} ${m.words.join(' ')}${marks(m)}`];
+    if (m.description)
+        lines.push('', m.description);
+    lines.push('', `${m.httpMethod} ${model.rootUrl}${model.servicePath}${m.path}`, `id: ${m.id}`);
+    lines.push('', m.parameters.size > 0 ? 'params (--params):' : 'params: none');
+    for (const [name, p] of m.parameters) {
+        const facts = [
+            p.location,
+            p.type,
+            requiredFact(p),
+            p.repeated && 'repeated',
+            p.enum && `enum: ${p.enum.join('|')}`,
+            p.pattern && `pattern: ${p.pattern}`,
+        ].filter(Boolean);
+        lines.push(`  ${name}  ${facts.join(', ')}`);
+        // Descriptions carry Markdown (tables, lists): keep their lines, indented.
+        if (p.description)
+            lines.push(p.description.trim().replace(/^/gm, '      '));
+    }
+    lines.push('', `body (--body): ${m.request ?? 'none'}`, `response: ${m.response ?? 'none'}`);
+    if (m.upload) {
+        const protocols = m.upload.resumable ? 'media, multipart, resumable' : 'media, multipart';
+        const max = m.upload.maxSize ? `; max ${m.upload.maxSize}` : '';
+        lines.push(`upload: ${protocols}; accept ${m.upload.accept.join(', ') || 'any'}${max}`);
+    }
+    if (m.download)
+        lines.push('download: yes');
+    lines.push(`scopes: ${m.scopes.join(', ') || 'none'}`);
+    if (m.deprecated)
+        lines.push(`deprecated${m.deprecated.source ? `: ${m.deprecated.source}` : ''}`);
+    if (m.retired)
+        lines.push(`retired: ${m.retired.reason} (${m.retired.source})`);
+    if (m.paid)
+        lines.push(`paid: ${m.paid.reason} (${m.paid.source})`);
+    if (m.unavailable)
+        lines.push('unavailable: scope not grantable');
+    if (model.documentationLink)
+        lines.push(`docs: ${model.documentationLink}`);
+    return `${lines.join('\n')}\n`;
+}
+const GENERATED = 'Generated by `pnpm gen:skill` from the discovery document. Do not edit.';
+const AUTH_LABEL = { oauth: 'OAuth', apiKey: 'API key' };
+const cell = (text) => text.replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim();
+// A table cell holds one sentence; the full text is in `--help`.
+const oneLine = (description = '') => description
+    .trim()
+    .split('\n')[0]
+    .split(/(?<=\.)\s+(?=[A-Z*])/)[0];
+// The first sentence, max 100 chars: one line of search hits and of `schema --find`.
+const brief = (description) => {
+    const sentence = oneLine(description);
+    const chars = [...sentence]; // code points: a cut never splits a surrogate pair
+    return chars.length > 100 ? `${chars.slice(0, 99).join('')}…` : sentence;
+};
+// Code-point order, so the output does not depend on the machine's locale.
+const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const byKey = (map) => [...map].sort(([a], [b]) => compare(a, b));
+export function indexMarkdown(models) {
+    const rows = models
+        .toSorted((a, b) => compare(a.api, b.api))
+        .map((m) => `| [\`${m.api}\`](${m.api}.md) | ${cell(m.title ?? m.name)} | ${m.version} | ${m.byId.size} | ${AUTH_LABEL[m.auth]} |`);
+    return [
+        '# gapi API reference',
+        '',
+        GENERATED,
+        '',
+        '| api | title | version | methods | auth |',
+        '|---|---|---|---|---|',
+        ...rows,
+        '',
+    ].join('\n');
+}
+export function referenceMarkdown(model) {
+    const lines = [
+        `# gapi ${model.api}: ${model.title ?? model.name} ${model.version}`,
+        '',
+        GENERATED,
+        '',
+        `Auth: ${AUTH_LABEL[model.auth]}.${model.documentationLink ? ` Docs: ${model.documentationLink}` : ''}`,
+    ];
+    // Sorted by key: Google serves the same document with its keys in varying order.
+    const visit = (node, words) => {
+        if (words.length > 0 || node.methods.size > 0) {
+            lines.push('', `## ${['gapi', model.api, ...words].join(' ')}`);
+        }
+        if (node.methods.size > 0) {
+            lines.push('', '| command | HTTP | description | required params | body | marks |', '|---|---|---|---|---|---|', ...byKey(node.methods).map(([, m]) => referenceRow(model, m)));
+        }
+        for (const [key, child] of byKey(node.resources))
+            visit(child, [...words, key]);
+    };
+    visit(model, []);
+    return `${lines.join('\n')}\n`;
+}
+function referenceRow(model, m) {
+    const required = byKey(m.parameters)
+        .filter(([, p]) => requiredFact(p))
+        .map(([name, p]) => `\`${name}\`${p.required ? '' : ' (per description)'}`);
+    const marked = markList(m, { reasons: true }).join('; ');
+    return `| \`gapi ${model.api} ${m.words.join(' ')}\` | ${m.httpMethod} | ${cell(oneLine(m.description))} | ${required.join(', ')} | ${m.request ? `\`${m.request}\`` : ''} | ${cell(marked)} |`;
+}
+// One line per hit: command, marks, HTTP method, first sentence of the description.
+export function searchText(hits) {
+    return hits
+        .map(({ model, method: m }) => {
+        const line = `gapi ${model.api} ${m.words.join(' ')}${marks(m)}  ${m.httpMethod}  ${brief(m.description)}`;
+        return `${line.trimEnd()}\n`;
+    })
+        .join('');
+}
+// D9: a method's shape (request/response as schema names), or one document schema.
+export function schemaView(model, target, { resolveRefs }) {
+    // A method shape holds schema names, never a $ref, so --resolve-refs leaves it as is.
+    if ('method' in target) {
+        const m = target.method;
+        const shape = {
+            id: m.id,
+            httpMethod: m.httpMethod,
+            path: m.path,
+            description: m.description,
+            parameters: Object.fromEntries(m.parameters),
+            request: m.request,
+            response: m.response,
+            scopes: m.scopes,
+            supportsMediaUpload: m.upload !== undefined,
+            supportsMediaDownload: m.download !== undefined,
+        };
+        return `${JSON.stringify(shape, null, 2)}\n`;
+    }
+    const schema = model.schemas.get(target.schema);
+    const out = resolveRefs && schema ? expandObject(schema, model.schemas, [target.schema]) : schema;
+    return `${JSON.stringify(out, null, 2)}\n`;
+}
+// `--find`: one line per leaf of the expanded schema (a method: request and response) whose
+// path or printed sentence contains `word`, case-insensitive. A $ref the cycle guard left is a leaf.
+export function schemaFind(model, target, word) {
+    const roots = 'method' in target
+        ? [
+            ['request', target.method.request],
+            ['response', target.method.response],
+        ]
+        : [['', target.schema]];
+    const needle = word.toLowerCase();
+    const lines = [];
+    // An array or map item without a description takes its field's (Google puts it there).
+    const walk = (node, path, fieldDescription = '') => {
+        const own = typeof node.description === 'string' ? node.description : fieldDescription;
+        const props = isRecord(node.properties) ? Object.entries(node.properties) : [];
+        const children = [
+            ...props.map(([key, child]) => [
+                path ? `${path}.${key}` : key,
+                child,
+                '',
+            ]),
+            [`${path}[]`, node.items, own],
+            [`${path}{}`, node.additionalProperties, own],
+        ];
+        let leaf = true;
+        for (const [childPath, child, description] of children) {
+            if (!isRecord(child))
+                continue;
+            leaf = false;
+            walk(child, childPath, description);
+        }
+        const ref = typeof node.$ref === 'string' ? node.$ref : undefined;
+        const text = ref ? '' : brief(own);
+        if (!leaf || !`${path}\n${text}`.toLowerCase().includes(needle))
+            return;
+        const type = ref ? `$ref ${ref}` : `${String(node.type ?? 'any')}${node.enum ? ' enum' : ''}`;
+        lines.push(`${path}: ${type}${text ? ` — ${text}` : ''}`);
+    };
+    for (const [path, name] of roots) {
+        const schema = name ? model.schemas.get(name) : undefined;
+        const expanded = name && schema ? expandObject(schema, model.schemas, [name]) : undefined;
+        if (isRecord(expanded))
+            walk(expanded, path);
+    }
+    return lines.map((line) => `${line}\n`).join('');
+}
+function expandRefs(value, schemas, path) {
+    if (Array.isArray(value))
+        return value.map((v) => expandRefs(v, schemas, path));
+    return typeof value === 'object' && value !== null ? expandObject(value, schemas, path) : value;
+}
+// Replaces {"$ref": X, …} with schema X expanded, keeping the sibling keys.
+// A name already on the expansion path stays a {"$ref": X} with its siblings (cycle guard).
+function expandObject(obj, schemas, path) {
+    const ref = '$ref' in obj ? obj.$ref : undefined;
+    const name = typeof ref === 'string' && !path.includes(ref) ? ref : undefined;
+    const schema = name && schemas.get(name);
+    const own = Object.fromEntries(Object.entries(obj)
+        .filter(([k]) => !(schema && k === '$ref'))
+        .map(([k, v]) => [k, expandRefs(v, schemas, path)]));
+    return name && schema ? { ...expandObject(schema, schemas, [...path, name]), ...own } : own;
+}

package/dist/src/responses.js

@@ -0,0 +1,37 @@
+// Response cache (ADR 0001): one file per key under <config dir>/responses/, dir 700, files
+// 600, written by temp file + rename. Holds Google account data: login and logout clear it.
+import { hash } from 'node:crypto';
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeAtomic } from './catalog.js';
+export const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export function openResponses(dir) {
+    const file = (key) => join(dir, key);
+    // Every value that shapes the request or its output; `url` carries every query value.
+    const key = (call, identity) => hash('sha256', JSON.stringify([
+        identity,
+        call.httpMethod,
+        call.url,
+        call.headers,
+        call.body,
+        call.send,
+        call.send === 'pages' ? call.pageLimit : undefined,
+        call.decode !== undefined, // a helper's decoded output differs from the raw one
+    ]));
+    // When the entry was stored (epoch ms); undefined when there is none.
+    const mtime = (k) => stat(file(k)).then((s) => s.mtimeMs, () => undefined);
+    const get = (k) => readFile(file(k), 'utf8').catch(() => undefined);
+    const put = (k, text) => writeAtomic(file(k), text);
+    // Deletes every file (temp files too) older than the max age. Every run calls it, so
+    // account data never outlives 7 days on disk (YouTube policy, ADR 0001).
+    async function sweep() {
+        for (const name of await readdir(dir).catch(() => [])) {
+            const f = join(dir, name);
+            const s = await stat(f).catch(() => undefined);
+            if (s && Date.now() - s.mtimeMs > MAX_AGE_MS)
+                await rm(f, { force: true });
+        }
+    }
+    const clear = () => rm(dir, { recursive: true, force: true });
+    return { key, mtime, get, put, sweep, clear };
+}