google-apis-cli 0.3.0 → 0.4.0

package/dist/src/entities.js

@@ -0,0 +1,180 @@
+// Entities (#200 D6, ADR 0002): the offline index of the operator's own accounts, properties
+// and sites in <config dir>/entities.db, mode 600. Rows hold the Credentials identity and live
+// at most 7 days; login and logout delete the file. Nothing here ever picks an ID for a call.
+// shortcut: DatabaseSync is a deprecated alias of Database since Node v26.11.0 (DEP0210), switch
+// when @types/node types Database.
+import { existsSync } from 'node:fs';
+import { mkdir, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { GapiError } from './errors.js';
+import { isRecord } from './json.js';
+import { MAX_AGE_MS } from './responses.js';
+const VERSION = 1; // PRAGMA user_version; another value drops the file, sync rebuilds it
+const NOT_A_DATABASE = 26; // SQLITE_NOTADB: the file is dropped like another version
+const BUSY_MS = 5000; // another gapi process may hold the write lock
+const SCHEMA = `create virtual table if not exists entity using fts5(
+  api unindexed, kind unindexed, id, name, parent, domain, identity unindexed, synced unindexed,
+  tokenize = 'trigram')`;
+// Domain key: URL host, lower case (IDN as punycode), no leading `www.`.
+// shortcut: no public-suffix parsing, so `shop.acme.com` does not link to `acme.com`; upgrade
+// when a source needs subdomain linking.
+export function domainOf(uri) {
+    if (typeof uri !== 'string' || uri === '')
+        return undefined;
+    const bare = uri.replace(/^sc-domain:/, '');
+    const url = URL.parse(/^[a-z][a-z\d+.-]*:\/\//i.test(bare) ? bare : `https://${bare}`);
+    return url?.hostname.replace(/^www\./, '') || undefined;
+}
+// The record items of `data[key]`, for a source's `entities` mapping.
+export const items = (data, key) => isRecord(data) && Array.isArray(data[key]) ? data[key].filter(isRecord) : [];
+export const text = (v) => typeof v === 'string' && v ? v : undefined;
+// Schema version; undefined for a file that is not a database. Any other error (a lock) throws,
+// so a busy index is never dropped.
+function versionOf(db) {
+    try {
+        return Number(db.prepare('pragma user_version').get()?.user_version);
+    }
+    catch (e) {
+        if (e instanceof Error && 'errcode' in e && e.errcode === NOT_A_DATABASE)
+            return undefined;
+        throw e;
+    }
+}
+export function openEntities(file) {
+    const clear = async () => {
+        await Promise.all(['', '-journal'].map((s) => rm(`${file}${s}`, { force: true })));
+    };
+    // Created mode 600 before SQLite opens it (SQLite gives its journal the same mode). `fresh`:
+    // the file is empty, so it is new (or a racing process has not written it yet).
+    const create = async () => {
+        await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+        await writeFile(file, '', { mode: 0o600, flag: 'a' });
+        const fresh = (await stat(file)).size === 0;
+        return { db: new DatabaseSync(file, { timeout: BUSY_MS }), fresh };
+    };
+    // A new file gets the schema in place. A file of another schema version, or not a database
+    // at all, is dropped and rebuilt empty.
+    async function open() {
+        let { db, fresh } = await create();
+        try {
+            if (!fresh && versionOf(db) === VERSION)
+                return db;
+            if (!fresh) {
+                db.close();
+                await clear();
+                ({ db } = await create());
+            }
+            db.exec(SCHEMA);
+            db.exec(`pragma user_version = ${VERSION}`);
+            return db;
+        }
+        catch (e) {
+            if (db.isOpen)
+                db.close();
+            throw e;
+        }
+    }
+    async function use(fn) {
+        const db = await open();
+        try {
+            return fn(db);
+        }
+        finally {
+            db.close();
+        }
+    }
+    // Every run: rows older than the response cache max age go (ADR 0001 terms, ADR 0002).
+    async function sweep() {
+        if (!existsSync(file))
+            return;
+        await use((db) => db.prepare('delete from entity where synced < ?').run(Date.now() - MAX_AGE_MS));
+    }
+    // Reads every source of one API, then replaces that API's rows in one transaction; a
+    // failed call throws before the write, so the old rows stay. Rows of one kind and ID merge
+    // (later defined fields win), so a child can add a domain or name. Returns the row count.
+    async function sync(api, sources, identity, request) {
+        const merged = new Map();
+        const walk = async (source, parent) => {
+            const found = [];
+            const call = {
+                api: source.api,
+                method: source.method,
+                params: source.params?.(parent) ?? {},
+                body: source.body?.(parent),
+                headers: source.headers?.(parent),
+            };
+            for await (const page of request(call))
+                found.push(...source.entities(page, parent));
+            for (const e of found) {
+                const key = `${e.kind}\0${e.id}`;
+                const was = merged.get(key);
+                merged.set(key, {
+                    ...e,
+                    name: e.name ?? was?.name,
+                    parent: e.parent ?? was?.parent,
+                    domain: e.domain ?? was?.domain,
+                });
+            }
+            for (const e of found) {
+                const { children } = source;
+                const child = children && Object.hasOwn(children, e.kind) ? children[e.kind] : undefined;
+                if (child)
+                    await walk(child, e);
+            }
+        };
+        for (const source of sources)
+            await walk(source);
+        const rows = [...merged.values()];
+        const now = Date.now();
+        return use((db) => {
+            db.exec('begin');
+            try {
+                db.prepare('delete from entity where api = ? and identity = ?').run(api, identity);
+                const insert = db.prepare('insert into entity values (?, ?, ?, ?, ?, ?, ?, ?)');
+                for (const r of rows) {
+                    insert.run(api, r.kind, r.id, r.name ?? '', r.parent ?? '', r.domain ?? '', identity, now);
+                }
+                db.exec('commit');
+            }
+            catch (e) {
+                db.exec('rollback');
+                throw e;
+            }
+            return rows.length;
+        });
+    }
+    // Trigram match of each whitespace-separated term (any substring of 3+ characters), joined
+    // by OR, best 20 by bm25. Each term is one quoted FTS5 string, so no FTS5 syntax reaches the
+    // match. `empty`: the identity has no row (for `api`) at all.
+    async function find(query, { api, identity }) {
+        const terms = query.split(/\s+/).filter(Boolean);
+        const short = terms.find((t) => [...t].length < 3);
+        if (terms.length === 0 || short !== undefined) {
+            throw new GapiError(3, `find: each term needs 3 or more characters${short ? `: '${short}'` : ''}`);
+        }
+        if (identity === undefined || !existsSync(file))
+            return { hits: [], empty: true };
+        const match = terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(' OR ');
+        return use((db) => {
+            const scope = 'identity = ? and (? is null or api = ?)';
+            const count = db.prepare(`select count(*) as n from entity where ${scope}`);
+            const empty = count.get(identity, api ?? null, api ?? null)?.n === 0;
+            const hits = db
+                .prepare(`select api, kind, id, name, parent, domain, synced from entity
+           where entity match ? and ${scope} order by rank limit 20`)
+                .all(match, identity, api ?? null, api ?? null)
+                .map((r) => ({
+                api: String(r.api),
+                kind: String(r.kind),
+                id: String(r.id),
+                name: text(r.name),
+                parent: text(r.parent),
+                domain: text(r.domain),
+                synced: Number(r.synced),
+            }));
+            return { hits, empty };
+        });
+    }
+    return { sync, find, sweep, clear };
+}

package/dist/src/plan.js

@@ -80,7 +80,7 @@ export function plan(model, target, input, settings) {
     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 body = mode.send === 'pages' && method.paging === 'body' ? pagingBody(input) : input.body;
     const url = buildUrl(model, method, values, mode);
     const headers = contentHeaders(mode, body !== undefined);
     if (model.auth === 'oauth' && settings.project)
@@ -163,13 +163,27 @@ function sendMode(method, command, input) {
     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).
+    return { send: 'pages', pageLimit, follow: nextPage(method.paging) };
+}
+// Body paging: every page sends this object, from page 2 on with pageToken set (D6).
+function pagingBody(input) {
     const body = input.body ?? {};
     if (!isRecord(body))
         throw invalid('--page-all: --body must be a JSON object');
-    return { send: 'pages', pageLimit, paging: 'body', body };
+    return body;
+}
+// AIP-158 follow rule: repeat the request with only pageToken changed, until no nextPageToken.
+function nextPage(paging) {
+    return (data, last) => {
+        const token = isRecord(data) ? data.nextPageToken : undefined;
+        if (typeof token !== 'string' || !token)
+            return undefined;
+        if (paging === 'body')
+            return { ...last, body: { ...(isRecord(last.body) && last.body), pageToken: token } };
+        const url = new URL(last.url);
+        url.searchParams.set('pageToken', token);
+        return { ...last, url: url.href };
+    };
 }
 // D7: protocol defaults to multipart with --body, else media; the type must fit `accept`.
 function upload(method, command, path, input, hasBody) {

package/dist/src/render.js

@@ -1,9 +1,17 @@
-// 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…>';
+export const FIELDS_USAGE = 'gapi fields ads|sa360 <words…> | ga4-data <words…> --property <id>';
+export const FIELDS_HELP = `${FIELDS_USAGE}
+Max 20 ranked lines: <name>  <kind>  <first sentence of the description>.
+  ads, sa360  GAQL names (resource attributes, metrics., segments.) from the discovery document, no request
+  ga4-data    GA4 dimensions and metrics, custom ones included: one properties getMetadata request
+              (--property 123 or properties/123; 0 = the ones common to all properties)
+No --cache. Discovery has no GAQL compatibility (selectable_with): check it with
+googleAdsFields.search (gapi ads googleAdsFields search; sa360: searchAds360Fields search)`;
+export const ENTITIES_USAGE = 'gapi entities sync [<api>…] [--page-limit <n>] | find <words…> [--api <api>]';
 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]
@@ -12,6 +20,8 @@ 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
+${FIELDS_USAGE}
+${ENTITIES_USAGE}
 ${SCHEMA_USAGE}
 ${DISCOVERY_USAGE}
 ${AUTH_USAGE}
@@ -100,7 +110,7 @@ const oneLine = (description = '') => description
     .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) => {
+export 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;
@@ -161,6 +171,22 @@ export function searchText(hits) {
     })
         .join('');
 }
+// #200 D7: one line per field, the shape of search hits.
+export function fieldsText(fields) {
+    return fields
+        .map((f) => `${`${f.name}  ${f.kind}  ${brief(f.description)}`.trimEnd()}\n`)
+        .join('');
+}
+// #200 D6: tabs keep empty cells (no name, parent or domain) unambiguous for `cut`.
+export function entitiesText(hits) {
+    return hits
+        .map((h) => {
+        const date = new Date(h.synced).toISOString().slice(0, 10);
+        const cells = [h.api, h.kind, h.id, h.name, h.parent, h.domain, date];
+        return `${cells.map((c = '') => c.replace(/[\t\r\n]+/g, ' ')).join('\t')}\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.

package/dist/src/run.js

@@ -4,13 +4,14 @@ import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 import { openCatalog } from './catalog.js';
 import { configDir, openCredentials } from './credentials.js';
+import { openEntities } from './entities.js';
 import { GapiError, messageOf, reasonOf } from './errors.js';
 import { isRecord } from './json.js';
 import { parseJson, plan, resolve } from './plan.js';
-import { AUTH_USAGE, DISCOVERY_USAGE, levelText, methodHelp, rootHelp, SCHEMA_USAGE, SEARCH_USAGE, schemaFind, schemaView, searchText, } from './render.js';
+import { AUTH_USAGE, DISCOVERY_USAGE, ENTITIES_USAGE, entitiesText, FIELDS_HELP, FIELDS_USAGE, fieldsText, levelText, methodHelp, rootHelp, SCHEMA_USAGE, SEARCH_USAGE, schemaFind, schemaView, searchText, } from './render.js';
 import { MAX_AGE_MS, openResponses } from './responses.js';
-import { matchQuery, search } from './search.js';
-import { send } from './transport.js';
+import { FIELD_APIS, ga4Fields, gaqlFields, matchQuery, rankFields, search, } from './search.js';
+import { receive, send } from './transport.js';
 const GLOBAL_OPTIONS = {
     params: { type: 'string' },
     body: { type: 'string' },
@@ -76,7 +77,7 @@ function parse(args, options) {
         throw e instanceof GapiError ? e : new GapiError(3, messageOf(e));
     }
 }
-async function runAuth(sub, values, { io, creds, catalog, responses, }) {
+async function runAuth(sub, values, { io, creds, catalog, responses, entities, }) {
     // --help never starts a side effect: no server, no fetch, no file write.
     if (values.help) {
         io.stdout.write(`${AUTH_USAGE}\n`);
@@ -84,7 +85,8 @@ async function runAuth(sub, values, { io, creds, catalog, responses, }) {
     }
     if (sub === 'login') {
         const consent = await consentScopes(catalog);
-        await responses.clear(); // a new account starts with no stored responses
+        // A new account starts with no stored responses and no entities.
+        await Promise.all([responses.clear(), entities.clear()]);
         const tokens = await creds.login({ consent, manual: values.manual === true });
         io.stderr.write(`gapi: authorized (${tokens.refresh_token ? 'refresh token stored' : 'no refresh token'})\n`);
         return;
@@ -99,7 +101,7 @@ async function runAuth(sub, values, { io, creds, catalog, responses, }) {
     }
     if (sub === 'status') {
         const consent = await consentScopes(catalog);
-        io.stdout.write(`${JSON.stringify(await creds.status(consent), null, 2)}\n`);
+        printJson(io, `${JSON.stringify(await creds.status(consent))}\n`);
         return;
     }
     if (sub === 'logout') {
@@ -107,13 +109,155 @@ async function runAuth(sub, values, { io, creds, catalog, responses, }) {
             await creds.logout();
         }
         finally {
-            await responses.clear(); // also when the revoke fails: no account data stays on disk
+            // Also when the revoke fails: no account data stays on disk.
+            await Promise.all([responses.clear(), entities.clear()]);
         }
         io.stderr.write('gapi: credentials removed\n');
         return;
     }
     throw new GapiError(3, sub === undefined ? `usage: ${AUTH_USAGE}` : `unknown auth command: ${sub}`);
 }
+// #200 D6: `sync` stores each API's entity sources; `find` searches them offline.
+async function runEntities(args, { io, creds, catalog, entities }) {
+    const parsed = parse(args, {
+        help: { type: 'boolean' },
+        api: { type: 'string' },
+        'page-limit': { type: 'string' },
+    });
+    const { values } = parsed;
+    const [sub, ...positionals] = parsed.positionals;
+    if (values.help) {
+        io.stdout.write(`${ENTITIES_USAGE}\n`);
+        return;
+    }
+    if (sub !== 'find' && sub !== 'sync')
+        throw new GapiError(3, `usage: ${ENTITIES_USAGE}`);
+    const other = sub === 'find' ? 'page-limit' : 'api';
+    if (values[other] !== undefined)
+        throw new GapiError(3, `--${other}: not an option of ${sub}`);
+    const identity = await creds.identity({ kind: 'oauth', scopes: [] });
+    const sourcesOf = (api) => {
+        if (!Object.hasOwn(catalog.entries, api))
+            throw new GapiError(3, `unknown api: ${api}`);
+        const sources = catalog.entries[api].entities ?? [];
+        if (sources.length === 0)
+            throw new GapiError(3, `${api} has no entity sources`);
+        return sources;
+    };
+    if (sub === 'find') {
+        const api = typeof values.api === 'string' ? values.api : undefined;
+        if (api !== undefined)
+            sourcesOf(api);
+        const { hits, empty } = await entities.find(positionals.join(' '), { api, identity });
+        if (empty)
+            io.stderr.write('gapi: entities index is empty or older than 7 days; run gapi entities sync\n');
+        if (hits.length === 0)
+            io.stderr.write('gapi: no match\n');
+        io.stdout.write(entitiesText(hits));
+        return;
+    }
+    const limit = typeof values['page-limit'] === 'string' ? values['page-limit'] : '10';
+    if (!/^[1-9]\d*$/.test(limit))
+        throw new GapiError(3, '--page-limit must be a positive integer');
+    const apis = positionals.length > 0
+        ? [...new Set(positionals)]
+        : Object.keys(catalog.entries)
+            .filter((a) => catalog.entries[a].entities?.length)
+            .toSorted();
+    const sources = apis.map((a) => ({ api: a, sources: sourcesOf(a) }));
+    if (identity === undefined)
+        throw new GapiError(2, 'no refresh token; run gapi auth login');
+    // Cost first: one call per top-level source, then one per parent entity of a child source.
+    const children = new Set();
+    const each = (api, list) => {
+        for (const s of list) {
+            for (const [kind, child] of Object.entries(s.children ?? {})) {
+                children.add(`${api} ${kind}`);
+                each(api, [child]);
+            }
+        }
+    };
+    for (const s of sources)
+        each(s.api, s.sources);
+    const top = sources.reduce((n, s) => n + s.sources.length, 0);
+    const then = [...children].map((c) => `, then 1 per ${c}`).join('');
+    io.stderr.write(`gapi: entities sync: ${top} list calls${then}; max ${limit} pages per list\n`);
+    let failed = 0;
+    for (const { api, sources: list } of sources) {
+        try {
+            // A source may call another entry's method (`api`); its settings and headers apply.
+            const request = async function* ({ api: owner = api, method, params, body, headers, }) {
+                const model = await catalog.load(owner);
+                const settings = await creds.settings({}, model.headers);
+                const paged = model.byId.get(method)?.paging !== undefined;
+                const call = plan(model, method, { params, body, pageAll: paged, pageLimit: paged ? limit : undefined }, { ...settings, headers: { ...settings.headers, ...headers } });
+                for (const w of call.warnings)
+                    io.stderr.write(`gapi: warning: ${w}\n`);
+                yield* receive(call, { fetch: io.fetch, authorize: creds.authorize, sleep: io.sleep });
+            };
+            const n = await entities.sync(api, list, identity, request);
+            io.stdout.write(`${api}: ${n} entities\n`);
+        }
+        catch (e) {
+            failed++;
+            io.stdout.write(`${api}: failed, old rows kept: ${messageOf(e)}\n`);
+        }
+    }
+    if (failed > 0)
+        throw new GapiError(1, `${failed} of ${sources.length} entity sources failed`);
+}
+// #200 D7: GAQL names offline from the discovery document, GA4 names from one getMetadata call.
+async function runFields(args, { io, creds, catalog }) {
+    const { values, positionals } = parse(args, {
+        property: { type: 'string' },
+        cache: { type: 'string' },
+        help: { type: 'boolean' },
+    });
+    if (values.help) {
+        io.stdout.write(`${FIELDS_HELP}\n`);
+        return;
+    }
+    // ADR 0001 keys a cache entry by the request, so two queries would share one entry.
+    if (values.cache !== undefined)
+        throw new GapiError(3, '--cache: fields is not cacheable');
+    const [name, ...words] = positionals;
+    if (name === undefined)
+        throw new GapiError(3, `usage: ${FIELDS_USAGE}`);
+    if (!FIELD_APIS.includes(name)) {
+        throw new GapiError(3, `fields: ${name} has no field source; supported: ${FIELD_APIS.join(', ')}`);
+    }
+    const query = words.join(' ');
+    matchQuery(query, FIELDS_USAGE); // no word → exit 3 before any document loads
+    const { property } = values;
+    if (name !== 'ga4-data' && property !== undefined) {
+        throw new GapiError(3, `--property: not an option of fields ${name}`);
+    }
+    if (name === 'ga4-data' && property === undefined) {
+        throw new GapiError(3, '--property is required');
+    }
+    const id = property?.replace(/^properties\//, '');
+    if (id !== undefined && !/^\d+$/.test(id)) {
+        throw new GapiError(3, `--property: ${property} is not a GA4 property id`);
+    }
+    const model = await catalog.load(name);
+    let fields = [];
+    if (id === undefined) {
+        fields = gaqlFields(model);
+    }
+    else {
+        const settings = await creds.settings({}, model.headers);
+        const call = plan(model, 'analyticsdata.properties.getMetadata', { params: { name: `properties/${id}/metadata` } }, settings);
+        for (const w of call.warnings)
+            io.stderr.write(`gapi: warning: ${w}\n`);
+        const opts = { fetch: io.fetch, authorize: creds.authorize, sleep: io.sleep };
+        for await (const data of receive(call, opts))
+            fields = ga4Fields(data);
+    }
+    const hits = rankFields(fields, query);
+    if (hits.length === 0)
+        io.stderr.write('gapi: no match\n');
+    io.stdout.write(fieldsText(hits));
+}
 // D8 consent set: every entry's per-method scope plus its entry scopes (identity is added by login).
 async function consentScopes(catalog) {
     const models = await Promise.all(Object.keys(catalog.entries).map((api) => catalog.load(api)));
@@ -159,6 +303,9 @@ async function dispatch(argv, io) {
     });
     const responses = openResponses(join(dir, 'responses'));
     await responses.sweep();
+    const entities = openEntities(join(dir, 'entities.db'));
+    // shortcut: a lock or disk error skips this run's sweep with a warning, the next run retries.
+    await entities.sweep().catch((e) => warn(`entities sweep skipped: ${messageOf(e)}`));
     // ADR 0001 eligibility, before any network call: the entry allows caching, the call is
     // one request or pages, the method is a GET or a `reads` POST.
     const cacheFor = async (call, model, values) => {
@@ -187,8 +334,10 @@ async function dispatch(argv, io) {
             manual: { type: 'boolean' },
             help: { type: 'boolean' },
         });
-        return runAuth(positionals[0], values, { io, creds, catalog, responses });
+        return runAuth(positionals[0], values, { io, creds, catalog, responses, entities });
     }
+    if (api === 'entities')
+        return runEntities(rest, { io, creds, catalog, entities });
     if (api === 'search') {
         // No option parse: a word like `-list` is query text (story 11).
         if (rest.includes('--help')) {
@@ -204,6 +353,8 @@ async function dispatch(argv, io) {
         io.stdout.write(searchText(hits));
         return;
     }
+    if (api === 'fields')
+        return runFields(rest, { io, creds, catalog });
     if (api === 'schema') {
         const { values, positionals } = parse(rest, {
             'resolve-refs': { type: 'boolean' },
@@ -322,6 +473,24 @@ async function dispatch(argv, io) {
     const cache = await cacheFor(call, model, values);
     return perform(call, dryRun, io, creds.authorize, { responses, cache });
 }
+// The one JSON writer (epic #200 D2): compact lines stay as they are off a terminal (agents), each
+// line gets a 2-space indent on a terminal (operators).
+function printJson(io, lines) {
+    if (!io.stdout.isTTY)
+        return io.stdout.write(lines);
+    let text;
+    try {
+        const values = lines
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+        text = values.map((v) => `${JSON.stringify(v, null, 2)}\n`).join('');
+    }
+    catch {
+        text = lines; // a cache entry stored before #205 is already indented
+    }
+    return io.stdout.write(text);
+}
 // Prints the plan's warnings, then the redacted request (--dry-run), the stored response
 // (a --cache hit) or the live response, which a --cache miss stores after a full success.
 async function perform(call, dryRun, io, authorize, { responses, cache }) {
@@ -349,11 +518,11 @@ async function perform(call, dryRun, io, authorize, { responses, cache }) {
                 : undefined,
             cache: cache && (stored === undefined ? 'miss' : 'hit'),
         };
-        io.stdout.write(`${JSON.stringify(request, null, 2)}\n`);
+        printJson(io, `${JSON.stringify(request)}\n`);
         return;
     }
     if (stored !== undefined && mtime !== undefined) {
-        io.stdout.write(stored);
+        printJson(io, stored);
         io.stderr.write(`gapi: cached response from ${new Date(mtime).toISOString()}\n`);
         return;
     }
@@ -361,7 +530,7 @@ async function perform(call, dryRun, io, authorize, { responses, cache }) {
     const out = {
         write: (chunk) => {
             chunks.push(chunk);
-            return io.stdout.write(chunk);
+            return printJson(io, chunk);
         },
     };
     await send(call, { fetch: io.fetch, authorize, out, sleep: io.sleep });