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

package/src/clients.mjs

@@ -1,221 +1,221 @@
-import { existsSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { createInterface } from 'node:readline';
-import { DEFAULT_ALIAS, checkAlias, describeClientAlias } from './aliases.mjs';
-
-/** Same rules as the platform: HawkSearch client ids, and the optional label kept with them. */
-export const CLIENT_ID = /^[A-Za-z0-9_.-]{1,100}$/;
-const MAX_CLIENT_NAME = 100;
-
-const USAGE = `Usage:
-  hawk-app clients
-  hawk-app clients search <name or id>
-  hawk-app clients add <id> [<id> …] [--name "<name>"] [--alias <name>]
-  hawk-app clients add --pick "<name or id>" [--alias <name>]
-  hawk-app clients exclude <id> [--name "<name>"]
-  hawk-app clients remove <id>`;
-
-const VISIBILITY = {
-    allowList: 'allowList: only the clients listed with + have the app',
-    all: 'all: every client has the app, except the ones listed with -',
-    internal: 'internal: Bridgeline users only; the client list is ignored',
-};
-
-/**
- * `hawk-app clients …`: which clients have the app. The platform registry is the only source of truth (not
- * hawk-app.json); the same list is changed in the Hawk Analytics portal. Changes apply at once, without a deploy or
- * approval, and are recorded in the app's history. `client` is a factory, so a usage mistake shows before any login check.
- * `names: false` prints ids only (the MCP server: client names stay out of the assistant's context). `choose` asks the
- * person at the terminal to pick one of the matches for `add --pick`.
- */
-export async function clientsCommand({ client, manifest, sub = 'list', args = [], flags = {}, names = true, choose = chooseOnTerminal, log = console.log }) {
-    if (sub === 'search') return searchClients({ client, text: args.join(' ').trim(), log });
-    const slug = manifest.slug;
-    const label = names ? labelOf : (c) => c.id;
-    switch (sub) {
-        case 'list': {
-            const { visibility, clients = [] } = await call(() => client().listClients(slug), slug);
-            log(`${slug}: visibility ${VISIBILITY[visibility] ?? visibility}`);
-            if (!clients.length) {
-                log(visibility === 'allowList' ? '  no client has it yet. Add one with `hawk-app clients add <id>`.' : '  (no clients listed)');
-                return 0;
-            }
-            for (const c of clients) log(`  ${c.enabled ? '+' : '-'} ${label(c)}${describeClientAlias(c)}`);
-            return 0;
-        }
-
-        case 'add':
-        case 'exclude': {
-            const enabled = sub === 'add';
-            if (flags.alias !== undefined && !enabled) throw new Error(`--alias is for \`clients add\`.\n${USAGE}`);
-            const alias = flags.alias === undefined ? undefined : checkAlias(flags.alias, { allowDefault: true });
-            const ids = enabled && flags.pick !== undefined ? [await pickClient({ client, text: flags.pick, slug, choose, log })] : checkIds(args);
-            if (ids[0] === null) {
-                log('Cancelled: no client was added.');
-                return 1;
-            }
-            const name = checkName(flags.name);
-            if (name !== undefined && ids.length > 1) throw new Error('--name labels one client: add the clients one at a time to name them.');
-            // Read first: the warnings below need the registered visibility (it can differ from hawk-app.json until review).
-            const { visibility } = await call(() => client().listClients(slug), slug);
-            // --alias: the version they get. On an alias whose version isn't approved, only Bridgeline staff in them see it.
-            let refused = 0;
-            for (const id of ids) {
-                try {
-                    const saved = await call(() => client().setClient(slug, id, { enabled, ...(alias ? { alias } : {}), ...(name !== undefined ? { name } : {}) }), slug);
-                    const where = saved.alias
-                        ? ` on ${saved.alias}${saved.aliasStatus && saved.aliasStatus !== 'approved' ? ` (${saved.aliasStatus}: only Bridgeline staff in it see the app until its version is approved)` : ''}`
-                        : '';
-                    log(`✔ ${enabled ? 'Added' : 'Excluded'} ${label(saved)} ${enabled ? 'to' : 'from'} ${slug}${where}. It applies now (recorded in the app's history).`);
-                } catch (error) {
-                    if (error.data?.code !== 'approver_required') throw error;
-                    refused++;
-                    log(`✖ ${id}'s users see ${slug} now: only an approver can change what it gets (the app's Rollout tab in the Hawk Analytics portal, or HawkSearch).`);
-                }
-            }
-            if (!enabled && visibility !== 'all') log(`! ${slug} has visibility "${visibility}": excluding a client only has an effect with visibility "all".`);
-            if (enabled && visibility === 'internal') log(`! ${slug} has visibility "internal": only Bridgeline users see it until its visibility changes.`);
-            if (alias && alias !== DEFAULT_ALIAS && refused < ids.length) log(`  Back to the default version: \`hawk-app clients add <id> --alias ${DEFAULT_ALIAS}\`.`);
-            return refused ? 1 : 0;
-        }
-
-        case 'remove': {
-            const id = checkId(args[0]);
-            try {
-                await call(() => client().removeClient(slug, id), slug);
-            } catch (error) {
-                if (error.data?.code === 'client_not_found') throw new Error(`${id} is not in ${slug}'s client list; nothing was changed.`);
-                throw error;
-            }
-            log(`✔ Removed ${id} from ${slug}'s client list. It applies now (recorded in the app's history).`);
-            return 0;
-        }
-
-        default:
-            throw new Error(`Unknown clients command "${sub}".\n${USAGE}`);
-    }
-}
-
-/**
- * `hawk-app clients search <text>`: the environment's clients whose name or id matches (the Hawk Analytics portal's client
- * list), to find the id to add. Needs no app: it reads the list, nothing else.
- */
-async function searchClients({ client, text, log }) {
-    if (text.length < 2) throw new Error(`Search with at least 2 characters of a client's name or id.\n${USAGE}`);
-    const { clients = [], more } = await client().searchClients(text);
-    if (!clients.length) {
-        log(`No client matches "${text}". Try another part of its name, or the id the dashboard shows (e.g. e3141).`);
-        return 0;
-    }
-    log(`Clients matching "${text}"${more ? ' (the best matches; search for more of the name to narrow it down)' : ''}:`);
-    for (const c of clients) log(`  ${labelOf(c)}`);
-    log('Add one with `hawk-app clients add <id>`.');
-    return 0;
-}
-
-/**
- * `clients add --pick "<text>"`: finds the matching clients and has the person at the terminal pick one. The id, or
- * null when they cancel. This is where the MCP server sends people whose assistant can't show a picker, so the names are
- * only ever on their screen.
- */
-async function pickClient({ client, text, slug, choose, log }) {
-    const wanted = typeof text === 'string' ? text.trim() : '';
-    if (wanted.length < 2) throw new Error(`--pick needs at least 2 characters of a client's name or id, e.g. --pick "outdoor".\n${USAGE}`);
-    const { clients = [], more } = await client().searchClients(wanted);
-    if (!clients.length) throw new Error(`No client matches "${wanted}". Try another part of its name, or the id the dashboard shows (e.g. e3141).`);
-    const picked = await choose(`Which client should get ${slug}?${more ? ' (the best matches; cancel and use more of the name if yours is missing)' : ''}`, clients.map(labelOf));
-    if (picked === undefined) throw new Error('Picking a client needs a terminal. Run `hawk-app clients search` and then `hawk-app clients add <id>` instead.');
-    return picked === null ? null : clients[picked].id;
-}
-
-/**
- * `hawk-app dev` without a client: asks for part of a client's name, then which of the matches. The id; throws when
- * there's no terminal or nothing is picked.
- */
-export async function pickDevClient({ client, slug, ask = askOnTerminal, choose = chooseOnTerminal, log = console.log }) {
-    const noTerminal = 'Which client? Run `hawk-app dev --client <id>` (find the id with `hawk-app clients search <name>`).';
-    for (;;) {
-        const text = await ask(`Run ${slug} with which client's data? Part of its name or id: `);
-        if (text === undefined) throw new Error(noTerminal);
-        if (!text.trim()) throw new Error('No client picked.');
-        if (text.trim().length < 2) {
-            log('  At least 2 characters, please.');
-            continue;
-        }
-        const { clients = [], more } = await client().searchClients(text.trim());
-        if (!clients.length) {
-            log(`  No client matches "${text.trim()}". Try another part of its name, or its id (e.g. e3141).`);
-            continue;
-        }
-        const picked = await choose(`Which client?${more ? ' (the best matches; Enter and use more of the name if yours is missing)' : ''}`, clients.map(labelOf));
-        if (picked === undefined) throw new Error(noTerminal);
-        if (picked !== null) return clients[picked].id;
-    }
-}
-
-/** Saves the dev client in the project's .env.local (git-ignored), replacing an earlier one. */
-export async function rememberDevClient(projectDir, id) {
-    const file = join(projectDir, '.env.local');
-    const text = existsSync(file) ? await readFile(file, 'utf8') : '';
-    const kept = text.split(/\r?\n/).filter((line) => line && !/^\s*(export\s+)?HAWK_APPS_DEV_CLIENT\s*=/.test(line));
-    await writeFile(file, [...kept, `HAWK_APPS_DEV_CLIENT=${id}`, ''].join('\n'));
-}
-
-/** A line of text from the terminal; undefined when there's no terminal. */
-export function askOnTerminal(question, { input = process.stdin, output = process.stdout } = {}) {
-    if (!input.isTTY) return Promise.resolve(undefined);
-    return new Promise((resolve) => {
-        const rl = createInterface({ input, output });
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer);
-        });
-    });
-}
-
-/** Numbered choices on the terminal: the index picked, null for none (Enter), undefined when there's no terminal. */
-export function chooseOnTerminal(question, options, { input = process.stdin, output = process.stdout } = {}) {
-    if (!input.isTTY) return Promise.resolve(undefined);
-    return new Promise((resolve) => {
-        const rl = createInterface({ input, output });
-        output.write(`${question}\n${options.map((o, i) => `  ${i + 1}. ${o}`).join('\n')}\n`);
-        rl.question(`Number (Enter to cancel): `, (answer) => {
-            rl.close();
-            const n = Number(answer.trim());
-            resolve(Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : null);
-        });
-    });
-}
-
-/** Platform calls, saying how to add the app when it isn't on the platform yet. */
-async function call(fn, slug) {
-    try {
-        return await fn();
-    } catch (error) {
-        if (error.data?.code === 'app_not_found') throw new Error(`${slug} isn't on the platform yet: \`npm run app:dev\` or \`npm run app:deploy\` adds it.`);
-        throw error;
-    }
-}
-
-const labelOf = (c) => `${c.id}${c.name ? ` (${c.name})` : ''}`;
-
-
-
-function checkIds(ids) {
-    if (!ids.length) throw new Error(USAGE);
-    return [...new Set(ids.map(checkId))];
-}
-
-function checkId(id) {
-    if (!id) throw new Error(USAGE);
-    if (!CLIENT_ID.test(id)) throw new Error(`"${id}" is not a valid client id: 1-100 letters, digits, "_", "." or "-" (e.g. e3141).`);
-    return id;
-}
-
-function checkName(name) {
-    if (name === undefined) return undefined;
-    if (typeof name !== 'string') throw new Error('--name needs a value, e.g. --name "Outdoor Demo".');
-    if (name.length > MAX_CLIENT_NAME) throw new Error(`--name is longer than ${MAX_CLIENT_NAME} characters.`);
-    return name;
-}
+import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { DEFAULT_ALIAS, checkAlias, describeClientAlias } from './aliases.mjs';
+
+/** Same rules as the platform: HawkSearch client ids, and the optional label kept with them. */
+export const CLIENT_ID = /^[A-Za-z0-9_.-]{1,100}$/;
+const MAX_CLIENT_NAME = 100;
+
+const USAGE = `Usage:
+  hawk-app clients
+  hawk-app clients search <name or id>
+  hawk-app clients add <id> [<id> …] [--name "<name>"] [--alias <name>]
+  hawk-app clients add --pick "<name or id>" [--alias <name>]
+  hawk-app clients exclude <id> [--name "<name>"]
+  hawk-app clients remove <id>`;
+
+const VISIBILITY = {
+    allowList: 'allowList: only the clients listed with + have the app',
+    all: 'all: every client has the app, except the ones listed with -',
+    internal: 'internal: Bridgeline users only; the client list is ignored',
+};
+
+/**
+ * `hawk-app clients …`: which clients have the app. The platform registry is the only source of truth (not
+ * hawk-app.json); the same list is changed in the Hawk Analytics portal. Changes apply at once, without a deploy or
+ * approval, and are recorded in the app's history. `client` is a factory, so a usage mistake shows before any login check.
+ * `names: false` prints ids only (the MCP server: client names stay out of the assistant's context). `choose` asks the
+ * person at the terminal to pick one of the matches for `add --pick`.
+ */
+export async function clientsCommand({ client, manifest, sub = 'list', args = [], flags = {}, names = true, choose = chooseOnTerminal, log = console.log }) {
+    if (sub === 'search') return searchClients({ client, text: args.join(' ').trim(), log });
+    const slug = manifest.slug;
+    const label = names ? labelOf : (c) => c.id;
+    switch (sub) {
+        case 'list': {
+            const { visibility, clients = [] } = await call(() => client().listClients(slug), slug);
+            log(`${slug}: visibility ${VISIBILITY[visibility] ?? visibility}`);
+            if (!clients.length) {
+                log(visibility === 'allowList' ? '  no client has it yet. Add one with `hawk-app clients add <id>`.' : '  (no clients listed)');
+                return 0;
+            }
+            for (const c of clients) log(`  ${c.enabled ? '+' : '-'} ${label(c)}${describeClientAlias(c)}`);
+            return 0;
+        }
+
+        case 'add':
+        case 'exclude': {
+            const enabled = sub === 'add';
+            if (flags.alias !== undefined && !enabled) throw new Error(`--alias is for \`clients add\`.\n${USAGE}`);
+            const alias = flags.alias === undefined ? undefined : checkAlias(flags.alias, { allowDefault: true });
+            const ids = enabled && flags.pick !== undefined ? [await pickClient({ client, text: flags.pick, slug, choose, log })] : checkIds(args);
+            if (ids[0] === null) {
+                log('Cancelled: no client was added.');
+                return 1;
+            }
+            const name = checkName(flags.name);
+            if (name !== undefined && ids.length > 1) throw new Error('--name labels one client: add the clients one at a time to name them.');
+            // Read first: the warnings below need the registered visibility (it can differ from hawk-app.json until review).
+            const { visibility } = await call(() => client().listClients(slug), slug);
+            // --alias: the version they get. On an alias whose version isn't approved, only Bridgeline staff in them see it.
+            let refused = 0;
+            for (const id of ids) {
+                try {
+                    const saved = await call(() => client().setClient(slug, id, { enabled, ...(alias ? { alias } : {}), ...(name !== undefined ? { name } : {}) }), slug);
+                    const where = saved.alias
+                        ? ` on ${saved.alias}${saved.aliasStatus && saved.aliasStatus !== 'approved' ? ` (${saved.aliasStatus}: only Bridgeline staff in it see the app until its version is approved)` : ''}`
+                        : '';
+                    log(`✔ ${enabled ? 'Added' : 'Excluded'} ${label(saved)} ${enabled ? 'to' : 'from'} ${slug}${where}. It applies now (recorded in the app's history).`);
+                } catch (error) {
+                    if (error.data?.code !== 'approver_required') throw error;
+                    refused++;
+                    log(`✖ ${id}'s users see ${slug} now: only an approver can change what it gets (the app's Rollout tab in the Hawk Analytics portal, or HawkSearch).`);
+                }
+            }
+            if (!enabled && visibility !== 'all') log(`! ${slug} has visibility "${visibility}": excluding a client only has an effect with visibility "all".`);
+            if (enabled && visibility === 'internal') log(`! ${slug} has visibility "internal": only Bridgeline users see it until its visibility changes.`);
+            if (alias && alias !== DEFAULT_ALIAS && refused < ids.length) log(`  Back to the default version: \`hawk-app clients add <id> --alias ${DEFAULT_ALIAS}\`.`);
+            return refused ? 1 : 0;
+        }
+
+        case 'remove': {
+            const id = checkId(args[0]);
+            try {
+                await call(() => client().removeClient(slug, id), slug);
+            } catch (error) {
+                if (error.data?.code === 'client_not_found') throw new Error(`${id} is not in ${slug}'s client list; nothing was changed.`);
+                throw error;
+            }
+            log(`✔ Removed ${id} from ${slug}'s client list. It applies now (recorded in the app's history).`);
+            return 0;
+        }
+
+        default:
+            throw new Error(`Unknown clients command "${sub}".\n${USAGE}`);
+    }
+}
+
+/**
+ * `hawk-app clients search <text>`: the environment's clients whose name or id matches (the Hawk Analytics portal's client
+ * list), to find the id to add. Needs no app: it reads the list, nothing else.
+ */
+async function searchClients({ client, text, log }) {
+    if (text.length < 2) throw new Error(`Search with at least 2 characters of a client's name or id.\n${USAGE}`);
+    const { clients = [], more } = await client().searchClients(text);
+    if (!clients.length) {
+        log(`No client matches "${text}". Try another part of its name, or the id the dashboard shows (e.g. e3141).`);
+        return 0;
+    }
+    log(`Clients matching "${text}"${more ? ' (the best matches; search for more of the name to narrow it down)' : ''}:`);
+    for (const c of clients) log(`  ${labelOf(c)}`);
+    log('Add one with `hawk-app clients add <id>`.');
+    return 0;
+}
+
+/**
+ * `clients add --pick "<text>"`: finds the matching clients and has the person at the terminal pick one. The id, or
+ * null when they cancel. This is where the MCP server sends people whose assistant can't show a picker, so the names are
+ * only ever on their screen.
+ */
+async function pickClient({ client, text, slug, choose, log }) {
+    const wanted = typeof text === 'string' ? text.trim() : '';
+    if (wanted.length < 2) throw new Error(`--pick needs at least 2 characters of a client's name or id, e.g. --pick "outdoor".\n${USAGE}`);
+    const { clients = [], more } = await client().searchClients(wanted);
+    if (!clients.length) throw new Error(`No client matches "${wanted}". Try another part of its name, or the id the dashboard shows (e.g. e3141).`);
+    const picked = await choose(`Which client should get ${slug}?${more ? ' (the best matches; cancel and use more of the name if yours is missing)' : ''}`, clients.map(labelOf));
+    if (picked === undefined) throw new Error('Picking a client needs a terminal. Run `hawk-app clients search` and then `hawk-app clients add <id>` instead.');
+    return picked === null ? null : clients[picked].id;
+}
+
+/**
+ * `hawk-app dev` without a client: asks for part of a client's name, then which of the matches. The id; throws when
+ * there's no terminal or nothing is picked.
+ */
+export async function pickDevClient({ client, slug, ask = askOnTerminal, choose = chooseOnTerminal, log = console.log }) {
+    const noTerminal = 'Which client? Run `hawk-app dev --client <id>` (find the id with `hawk-app clients search <name>`).';
+    for (;;) {
+        const text = await ask(`Run ${slug} with which client's data? Part of its name or id: `);
+        if (text === undefined) throw new Error(noTerminal);
+        if (!text.trim()) throw new Error('No client picked.');
+        if (text.trim().length < 2) {
+            log('  At least 2 characters, please.');
+            continue;
+        }
+        const { clients = [], more } = await client().searchClients(text.trim());
+        if (!clients.length) {
+            log(`  No client matches "${text.trim()}". Try another part of its name, or its id (e.g. e3141).`);
+            continue;
+        }
+        const picked = await choose(`Which client?${more ? ' (the best matches; Enter and use more of the name if yours is missing)' : ''}`, clients.map(labelOf));
+        if (picked === undefined) throw new Error(noTerminal);
+        if (picked !== null) return clients[picked].id;
+    }
+}
+
+/** Saves the dev client in the project's .env.local (git-ignored), replacing an earlier one. */
+export async function rememberDevClient(projectDir, id) {
+    const file = join(projectDir, '.env.local');
+    const text = existsSync(file) ? await readFile(file, 'utf8') : '';
+    const kept = text.split(/\r?\n/).filter((line) => line && !/^\s*(export\s+)?HAWK_APPS_DEV_CLIENT\s*=/.test(line));
+    await writeFile(file, [...kept, `HAWK_APPS_DEV_CLIENT=${id}`, ''].join('\n'));
+}
+
+/** A line of text from the terminal; undefined when there's no terminal. */
+export function askOnTerminal(question, { input = process.stdin, output = process.stdout } = {}) {
+    if (!input.isTTY) return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+
+/** Numbered choices on the terminal: the index picked, null for none (Enter), undefined when there's no terminal. */
+export function chooseOnTerminal(question, options, { input = process.stdin, output = process.stdout } = {}) {
+    if (!input.isTTY) return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        output.write(`${question}\n${options.map((o, i) => `  ${i + 1}. ${o}`).join('\n')}\n`);
+        rl.question(`Number (Enter to cancel): `, (answer) => {
+            rl.close();
+            const n = Number(answer.trim());
+            resolve(Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : null);
+        });
+    });
+}
+
+/** Platform calls, saying how to add the app when it isn't on the platform yet. */
+async function call(fn, slug) {
+    try {
+        return await fn();
+    } catch (error) {
+        if (error.data?.code === 'app_not_found') throw new Error(`${slug} isn't on the platform yet: \`npm run app:dev\` or \`npm run app:deploy\` adds it.`);
+        throw error;
+    }
+}
+
+const labelOf = (c) => `${c.id}${c.name ? ` (${c.name})` : ''}`;
+
+
+
+function checkIds(ids) {
+    if (!ids.length) throw new Error(USAGE);
+    return [...new Set(ids.map(checkId))];
+}
+
+function checkId(id) {
+    if (!id) throw new Error(USAGE);
+    if (!CLIENT_ID.test(id)) throw new Error(`"${id}" is not a valid client id: 1-100 letters, digits, "_", "." or "-" (e.g. e3141).`);
+    return id;
+}
+
+function checkName(name) {
+    if (name === undefined) return undefined;
+    if (typeof name !== 'string') throw new Error('--name needs a value, e.g. --name "Outdoor Demo".');
+    if (name.length > MAX_CLIENT_NAME) throw new Error(`--name is longer than ${MAX_CLIENT_NAME} characters.`);
+    return name;
+}