@bridgeline-digital/hawk-app-cli 0.1.0-dev.20261020202308 → 0.1.0

package/src/data.mjs

@@ -1,169 +1,169 @@
-import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
-import { checkValue, parseParamValue, validateQuery } from './queries.mjs';
-
-const MAX_ROWS_SHOWN = 50;
-const MAX_CELL_WIDTH = 40;
-const RUN_TIMEOUT_MS = 5 * 60_000;
-const MAX_POLL_DELAY_MS = 5_000;
-const CLIENT_ID = /^[A-Za-z0-9]+$/;
-
-const USAGE = `Usage:
-  hawk-app data tables [--app <slug>]
-  hawk-app data describe <table>
-  hawk-app data run <queries/name.sql> --client <id> [--param name=value …]`;
-
-const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-
-/**
- * `hawk-app data …`: the tables app queries can use, and running a query against a client's data before deploying it.
- * `client` is a factory, so a usage mistake shows before any login check.
- */
-export async function dataCommand({ client, sub, args = [], flags = {}, sleep = wait, log = console.log }) {
-    switch (sub) {
-        case 'tables': {
-            const app = typeof flags.app === 'string' ? flags.app : undefined;
-            const all = (await client().dataTables(app)).tables ?? [];
-            const tables = all.filter((t) => !t.sensitive);
-            const sensitive = all.filter((t) => t.sensitive);
-            const width = Math.max(0, ...all.map((t) => t.name.length));
-            const line = (table) => `  ${table.name.padEnd(width)}  ${String(table.columns?.length ?? 0).padStart(3)} columns${table.partitioned ? '  partitioned (use {{partitions(from, to)}})' : ''}`;
-            log(`${tables.length} table${tables.length === 1 ? '' : 's'} available to queries (\`hawk-app data describe <table>\` for columns):`);
-            for (const table of tables) log(line(table));
-            if (sensitive.length) {
-                log('');
-                log(app
-                    ? `Sensitive tables (visitor-level data; only for apps Engineering opted in), for ${app}:`
-                    : 'Sensitive tables (visitor-level data; only for apps Engineering opted in; pass --app <slug> to check yours):');
-                for (const table of sensitive) log(`${line(table)}  ${table.available ? 'available' : 'not available'}`);
-            }
-            return 0;
-        }
-
-        case 'describe': {
-            const name = args[0];
-            if (!name) throw new Error(USAGE);
-            const { tables = [] } = await client().dataTables();
-            const table = tables.find((t) => t.name.toLowerCase() === name.toLowerCase());
-            if (!table) throw new Error(`Unknown table "${name}". Run \`hawk-app data tables\` to list the tables queries can use.`);
-            log(`${table.name}${table.partitioned ? '  (partitioned by year/month: filter with {{partitions(from, to)}})' : ''}`);
-            if (table.sensitive) log('  Sensitive: only apps Engineering opted in can query it.');
-            const width = Math.max(0, ...table.columns.map((c) => c.name.length));
-            for (const column of table.columns) log(`  ${column.name.padEnd(width)}  ${column.type}`);
-            return 0;
-        }
-
-        case 'run':
-            return run({ client, file: args[0], flags, sleep, log });
-
-        default:
-            throw new Error(sub ? `Unknown data command "${sub}".\n${USAGE}` : USAGE);
-    }
-}
-
-async function run({ client, file, flags, sleep, log }) {
-    if (!file || !file.endsWith('.sql')) throw new Error(USAGE);
-    const clientId = flags.client;
-    if (typeof clientId !== 'string' || !CLIENT_ID.test(clientId)) throw new Error('Pass the client to run against: --client <id> (letters and digits, e.g. e3141).');
-
-    const jsonFile = file.replace(/\.sql$/, '.json');
-    const name = basename(file, '.sql');
-    const sql = await readText(file);
-    let definition;
-    try {
-        definition = JSON.parse(await readText(jsonFile));
-    } catch (error) {
-        throw new Error(error instanceof SyntaxError ? `${jsonFile} is not valid JSON: ${error.message}` : error.message);
-    }
-    const errors = validateQuery(name, sql, definition);
-    if (errors.length) {
-        for (const error of errors) log(`✖ ${error}`);
-        throw new Error(`Fix ${file} first.`);
-    }
-
-    const params = definition.params ?? [];
-    const values = {};
-    for (const entry of flags.param ?? []) {
-        const eq = typeof entry === 'string' ? entry.indexOf('=') : -1;
-        if (eq <= 0) throw new Error(`--param needs name=value, not "${entry}".`);
-        const key = entry.slice(0, eq);
-        const param = params.find((p) => p.name === key);
-        if (!param) throw new Error(`"${key}" is not a parameter of ${name} (declared: ${params.map((p) => p.name).join(', ') || 'none'}).`);
-        const value = parseParamValue(param, entry.slice(eq + 1));
-        const problem = checkValue(param, value);
-        if (problem) throw new Error(`--param ${key} ${problem}.`);
-        values[key] = value;
-    }
-    const missing = params.filter((p) => p.required && p.default === undefined && !(p.name in values)).map((p) => p.name);
-    if (missing.length) throw new Error(`Missing required parameter${missing.length === 1 ? '' : 's'}: ${missing.map((m) => `--param ${m}=…`).join(' ')}`);
-
-    const platform = client();
-    const started = Date.now();
-    // 429 (too many queries running): wait and send again, 1 s, 2 s, 4 s, then every 5 s, never sooner than
-    // Retry-After, until the run's time is up.
-    let waited = false;
-    const retrying = async (send) => {
-        for (let attempt = 0; ; attempt++) {
-            try {
-                return await send();
-            } catch (error) {
-                if (error.status !== 429) throw error;
-                const wait = Math.max(Math.min(1000 * 2 ** attempt, MAX_POLL_DELAY_MS), error.retryAfterMs ?? 0);
-                if (Date.now() - started + wait > RUN_TIMEOUT_MS) throw error;
-                if (!waited) log('Too many queries are running; retrying…');
-                waited = true;
-                await sleep(wait);
-            }
-        }
-    };
-    let { status, data } = await retrying(() => platform.dataRun({ clientId, sql, params, values })).catch((error) => {
-        if (error.status === 403 && error.data?.code === 'not_available') {
-            error.message += '\n  `hawk-app data run` only works against the dev platform (--platform <dev url>).';
-        }
-        throw error;
-    });
-    for (let attempt = 0; status === 202; attempt++) {
-        if (Date.now() - started > RUN_TIMEOUT_MS) throw new Error(`The query did not finish within ${RUN_TIMEOUT_MS / 60_000} minutes.`);
-        if (attempt === 0) log('Running…');
-        await sleep(Math.min(Math.max(1000 * 2 ** attempt, data.retryAfterMs ?? 0), MAX_POLL_DELAY_MS));
-        ({ status, data } = await retrying(() => platform.dataExecution(data.executionId)));
-    }
-
-
-    printTable(data.columns ?? [], data.rows ?? [], log);
-    const rowCount = data.rowCount ?? data.rows?.length ?? 0;
-    const shown = Math.min(rowCount, MAX_ROWS_SHOWN, data.rows?.length ?? 0);
-    log(`${rowCount} row${rowCount === 1 ? '' : 's'}${rowCount > shown ? ` (showing the first ${shown})` : ''}, ${formatBytes(data.bytesScanned ?? 0)} scanned${data.cached ? ' (cached result)' : ''}.`);
-    return 0;
-}
-
-async function readText(file) {
-    try {
-        return await readFile(file, 'utf8');
-    } catch {
-        throw new Error(`Cannot read ${file}.`);
-    }
-}
-
-/** Prints up to 50 rows as an aligned text table. */
-export function printTable(columns, rows, log) {
-    if (!columns.length) return;
-    const cell = (value) => {
-        const text = value === null || value === undefined ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
-        const flat = text.replace(/\s+/g, ' ');
-        return flat.length > MAX_CELL_WIDTH ? `${flat.slice(0, MAX_CELL_WIDTH - 1)}…` : flat;
-    };
-    const shown = rows.slice(0, MAX_ROWS_SHOWN).map((row) => columns.map((_, i) => cell(row[i])));
-    const widths = columns.map((c, i) => Math.max(cell(c.name).length, ...shown.map((r) => r[i].length)));
-    const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
-    log(line(columns.map((c) => cell(c.name))));
-    log(widths.map((w) => '-'.repeat(w)).join('  '));
-    for (const row of shown) log(line(row));
-}
-
-export function formatBytes(bytes) {
-    if (bytes < 1024) return `${bytes} B`;
-    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
-    if (bytes < 1024 ** 3) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
-    return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
-}
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { checkValue, parseParamValue, validateQuery } from './queries.mjs';
+
+const MAX_ROWS_SHOWN = 50;
+const MAX_CELL_WIDTH = 40;
+const RUN_TIMEOUT_MS = 5 * 60_000;
+const MAX_POLL_DELAY_MS = 5_000;
+const CLIENT_ID = /^[A-Za-z0-9]+$/;
+
+const USAGE = `Usage:
+  hawk-app data tables [--app <slug>]
+  hawk-app data describe <table>
+  hawk-app data run <queries/name.sql> --client <id> [--param name=value …]`;
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * `hawk-app data …`: the tables app queries can use, and running a query against a client's data before deploying it.
+ * `client` is a factory, so a usage mistake shows before any login check.
+ */
+export async function dataCommand({ client, sub, args = [], flags = {}, sleep = wait, log = console.log }) {
+    switch (sub) {
+        case 'tables': {
+            const app = typeof flags.app === 'string' ? flags.app : undefined;
+            const all = (await client().dataTables(app)).tables ?? [];
+            const tables = all.filter((t) => !t.sensitive);
+            const sensitive = all.filter((t) => t.sensitive);
+            const width = Math.max(0, ...all.map((t) => t.name.length));
+            const line = (table) => `  ${table.name.padEnd(width)}  ${String(table.columns?.length ?? 0).padStart(3)} columns${table.partitioned ? '  partitioned (use {{partitions(from, to)}})' : ''}`;
+            log(`${tables.length} table${tables.length === 1 ? '' : 's'} available to queries (\`hawk-app data describe <table>\` for columns):`);
+            for (const table of tables) log(line(table));
+            if (sensitive.length) {
+                log('');
+                log(app
+                    ? `Sensitive tables (visitor-level data; only for apps Engineering opted in), for ${app}:`
+                    : 'Sensitive tables (visitor-level data; only for apps Engineering opted in; pass --app <slug> to check yours):');
+                for (const table of sensitive) log(`${line(table)}  ${table.available ? 'available' : 'not available'}`);
+            }
+            return 0;
+        }
+
+        case 'describe': {
+            const name = args[0];
+            if (!name) throw new Error(USAGE);
+            const { tables = [] } = await client().dataTables();
+            const table = tables.find((t) => t.name.toLowerCase() === name.toLowerCase());
+            if (!table) throw new Error(`Unknown table "${name}". Run \`hawk-app data tables\` to list the tables queries can use.`);
+            log(`${table.name}${table.partitioned ? '  (partitioned by year/month: filter with {{partitions(from, to)}})' : ''}`);
+            if (table.sensitive) log('  Sensitive: only apps Engineering opted in can query it.');
+            const width = Math.max(0, ...table.columns.map((c) => c.name.length));
+            for (const column of table.columns) log(`  ${column.name.padEnd(width)}  ${column.type}`);
+            return 0;
+        }
+
+        case 'run':
+            return run({ client, file: args[0], flags, sleep, log });
+
+        default:
+            throw new Error(sub ? `Unknown data command "${sub}".\n${USAGE}` : USAGE);
+    }
+}
+
+async function run({ client, file, flags, sleep, log }) {
+    if (!file || !file.endsWith('.sql')) throw new Error(USAGE);
+    const clientId = flags.client;
+    if (typeof clientId !== 'string' || !CLIENT_ID.test(clientId)) throw new Error('Pass the client to run against: --client <id> (letters and digits, e.g. e3141).');
+
+    const jsonFile = file.replace(/\.sql$/, '.json');
+    const name = basename(file, '.sql');
+    const sql = await readText(file);
+    let definition;
+    try {
+        definition = JSON.parse(await readText(jsonFile));
+    } catch (error) {
+        throw new Error(error instanceof SyntaxError ? `${jsonFile} is not valid JSON: ${error.message}` : error.message);
+    }
+    const errors = validateQuery(name, sql, definition);
+    if (errors.length) {
+        for (const error of errors) log(`✖ ${error}`);
+        throw new Error(`Fix ${file} first.`);
+    }
+
+    const params = definition.params ?? [];
+    const values = {};
+    for (const entry of flags.param ?? []) {
+        const eq = typeof entry === 'string' ? entry.indexOf('=') : -1;
+        if (eq <= 0) throw new Error(`--param needs name=value, not "${entry}".`);
+        const key = entry.slice(0, eq);
+        const param = params.find((p) => p.name === key);
+        if (!param) throw new Error(`"${key}" is not a parameter of ${name} (declared: ${params.map((p) => p.name).join(', ') || 'none'}).`);
+        const value = parseParamValue(param, entry.slice(eq + 1));
+        const problem = checkValue(param, value);
+        if (problem) throw new Error(`--param ${key} ${problem}.`);
+        values[key] = value;
+    }
+    const missing = params.filter((p) => p.required && p.default === undefined && !(p.name in values)).map((p) => p.name);
+    if (missing.length) throw new Error(`Missing required parameter${missing.length === 1 ? '' : 's'}: ${missing.map((m) => `--param ${m}=…`).join(' ')}`);
+
+    const platform = client();
+    const started = Date.now();
+    // 429 (too many queries running): wait and send again, 1 s, 2 s, 4 s, then every 5 s, never sooner than
+    // Retry-After, until the run's time is up.
+    let waited = false;
+    const retrying = async (send) => {
+        for (let attempt = 0; ; attempt++) {
+            try {
+                return await send();
+            } catch (error) {
+                if (error.status !== 429) throw error;
+                const wait = Math.max(Math.min(1000 * 2 ** attempt, MAX_POLL_DELAY_MS), error.retryAfterMs ?? 0);
+                if (Date.now() - started + wait > RUN_TIMEOUT_MS) throw error;
+                if (!waited) log('Too many queries are running; retrying…');
+                waited = true;
+                await sleep(wait);
+            }
+        }
+    };
+    let { status, data } = await retrying(() => platform.dataRun({ clientId, sql, params, values })).catch((error) => {
+        if (error.status === 403 && error.data?.code === 'not_available') {
+            error.message += '\n  `hawk-app data run` only works against the dev platform (--platform <dev url>).';
+        }
+        throw error;
+    });
+    for (let attempt = 0; status === 202; attempt++) {
+        if (Date.now() - started > RUN_TIMEOUT_MS) throw new Error(`The query did not finish within ${RUN_TIMEOUT_MS / 60_000} minutes.`);
+        if (attempt === 0) log('Running…');
+        await sleep(Math.min(Math.max(1000 * 2 ** attempt, data.retryAfterMs ?? 0), MAX_POLL_DELAY_MS));
+        ({ status, data } = await retrying(() => platform.dataExecution(data.executionId)));
+    }
+
+
+    printTable(data.columns ?? [], data.rows ?? [], log);
+    const rowCount = data.rowCount ?? data.rows?.length ?? 0;
+    const shown = Math.min(rowCount, MAX_ROWS_SHOWN, data.rows?.length ?? 0);
+    log(`${rowCount} row${rowCount === 1 ? '' : 's'}${rowCount > shown ? ` (showing the first ${shown})` : ''}, ${formatBytes(data.bytesScanned ?? 0)} scanned${data.cached ? ' (cached result)' : ''}.`);
+    return 0;
+}
+
+async function readText(file) {
+    try {
+        return await readFile(file, 'utf8');
+    } catch {
+        throw new Error(`Cannot read ${file}.`);
+    }
+}
+
+/** Prints up to 50 rows as an aligned text table. */
+export function printTable(columns, rows, log) {
+    if (!columns.length) return;
+    const cell = (value) => {
+        const text = value === null || value === undefined ? '' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+        const flat = text.replace(/\s+/g, ' ');
+        return flat.length > MAX_CELL_WIDTH ? `${flat.slice(0, MAX_CELL_WIDTH - 1)}…` : flat;
+    };
+    const shown = rows.slice(0, MAX_ROWS_SHOWN).map((row) => columns.map((_, i) => cell(row[i])));
+    const widths = columns.map((c, i) => Math.max(cell(c.name).length, ...shown.map((r) => r[i].length)));
+    const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+    log(line(columns.map((c) => cell(c.name))));
+    log(widths.map((w) => '-'.repeat(w)).join('  '));
+    for (const row of shown) log(line(row));
+}
+
+export function formatBytes(bytes) {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 ** 3) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
+}