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

package/src/scope-check.mjs

@@ -1,91 +1,91 @@
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { extname, join, relative } from 'node:path';
-
-/**
- * Which scopes the app's code needs: the bridge (and function) calls it makes, matched in its source files. A call whose
- * scope hawk-app.json lacks fails at run time with 403 scope_missing; `validate` and `deploy` say so first. Matching is
- * by the call's shape (`.ai.generate(`, `.storage.put(`…), so it works whatever the app calls its bridge object, and it
- * only warns: a false hit costs a line, a miss is no worse than today.
- */
-const RULES = [
-    { scope: 'reports:read', pattern: /\.analytics\.report\s*\(/ },
-    { scope: 'hawksearch:read', pattern: /\.dashboard\.get\s*\(/ },
-    { scope: 'hawksearch:write', pattern: /\.dashboard\.(post|put|delete)\s*\(/ },
-    { scope: 'data:read', pattern: /\.data\.query\s*\(/ },
-    { scope: 'functions:invoke', pattern: /\.functions\.(call|start|job|wait)\s*\(/ },
-    { scope: 'email:send', pattern: /\.email\.send\s*\(/ },
-    { scope: 'hawksearch:search', pattern: /\.hawksearch\.(search|autocomplete)\s*\(/ },
-    { scope: 'hawksearch:sysparams:write', pattern: /\.hawksearch\.systemParameters\.(list|get|set)\s*\(/ },
-    { scope: 'hawksearch:features:write', pattern: /\.hawksearch\.features\.(list|set|setFacet)\s*\(/ },
-    { scope: 'hawksearch:index:items', pattern: /\.hawksearch\.index\.items\.\w+\s*\(/ },
-    { scope: 'hawksearch:index', pattern: /\.hawksearch\.index\.(rebuild|status|wait|indexes|current)\s*\(/ },
-    { scope: 'hawksearch:index:manage', pattern: /\.hawksearch\.index\.(create|setCurrent|deleteIndex|rebuildAll)\s*\(/ },
-    { scope: 'hawksearch:recommendations', pattern: /\.hawksearch\.recommendations\s*\(/ },
-    { scope: 'storage', pattern: /\.storage\.(get|put|delete|list|batch|usage)\s*\(|\.storage\.files\.\w+\s*\(/ },
-    { scope: 'lambdas:invoke', pattern: /\.lambdas\.invoke\s*\(/ },
-    { scope: 'ai:invoke', pattern: /\.ai\.(generate|stream|info)\s*\(/ },
-    { scope: 'assistant', pattern: /\.assistant\.(ask|setContext)\s*\(/ },
-];
-
-const SOURCE = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.vue', '.svelte', '.html']);
-const SKIP = new Set(['node_modules', '.git', '.next', 'dist', 'out', 'build', 'coverage', '.turbo', '.vercel']);
-const MAX_FILES = 3000;
-const MAX_BYTES = 1024 * 1024;
-
-/** Source files of the project (not dependencies or build output), at most MAX_FILES. */
-async function sourceFiles(dir, found = []) {
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    } catch {
-        return found;
-    }
-    for (const entry of entries) {
-        if (found.length >= MAX_FILES) break;
-        if (entry.name.startsWith('.') && entry.name !== '.') continue;
-        const full = join(dir, entry.name);
-        if (entry.isDirectory()) {
-            if (!SKIP.has(entry.name)) await sourceFiles(full, found);
-        } else if (SOURCE.has(extname(entry.name))) {
-            found.push(full);
-        }
-    }
-    return found;
-}
-
-/**
- * The scopes the code uses that `scopes` lacks: [{ scope, file, line }] (the first place each one is used), relative to
- * `projectDir`.
- */
-export async function missingScopes(projectDir, scopes = []) {
-    const declared = new Set(scopes);
-    const wanted = RULES.filter((rule) => !declared.has(rule.scope));
-    if (!wanted.length) return [];
-    const found = new Map();
-    for (const file of await sourceFiles(projectDir)) {
-        if (found.size === wanted.length) break;
-        let text;
-        try {
-            if ((await stat(file)).size > MAX_BYTES) continue;
-            text = await readFile(file, 'utf8');
-        } catch {
-            continue;
-        }
-        for (const rule of wanted) {
-            if (found.has(rule.scope)) continue;
-            const match = rule.pattern.exec(text);
-            if (match) {
-                const line = text.slice(0, match.index).split('\n').length;
-                found.set(rule.scope, { scope: rule.scope, file: relative(projectDir, file).split('\\').join('/'), line });
-            }
-        }
-    }
-    return [...found.values()];
-}
-
-/** The warning for what's missing (null: nothing). */
-export function describeMissingScopes(missing) {
-    if (!missing.length) return null;
-    const where = missing.map((m) => `${m.scope} (${m.file}:${m.line})`).join(', ');
-    return `The code uses ${where}, which "scopes" in hawk-app.json doesn't have: add ${missing.length === 1 ? 'it' : 'them'}, or those calls fail with 403 scope_missing.`;
-}
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { extname, join, relative } from 'node:path';
+
+/**
+ * Which scopes the app's code needs: the bridge (and function) calls it makes, matched in its source files. A call whose
+ * scope hawk-app.json lacks fails at run time with 403 scope_missing; `validate` and `deploy` say so first. Matching is
+ * by the call's shape (`.ai.generate(`, `.storage.put(`…), so it works whatever the app calls its bridge object, and it
+ * only warns: a false hit costs a line, a miss is no worse than today.
+ */
+const RULES = [
+    { scope: 'reports:read', pattern: /\.analytics\.report\s*\(/ },
+    { scope: 'hawksearch:read', pattern: /\.dashboard\.get\s*\(/ },
+    { scope: 'hawksearch:write', pattern: /\.dashboard\.(post|put|delete)\s*\(/ },
+    { scope: 'data:read', pattern: /\.data\.query\s*\(/ },
+    { scope: 'functions:invoke', pattern: /\.functions\.(call|start|job|wait)\s*\(/ },
+    { scope: 'email:send', pattern: /\.email\.send\s*\(/ },
+    { scope: 'hawksearch:search', pattern: /\.hawksearch\.(search|autocomplete)\s*\(/ },
+    { scope: 'hawksearch:sysparams:write', pattern: /\.hawksearch\.systemParameters\.(list|get|set)\s*\(/ },
+    { scope: 'hawksearch:features:write', pattern: /\.hawksearch\.features\.(list|set|setFacet)\s*\(/ },
+    { scope: 'hawksearch:index:items', pattern: /\.hawksearch\.index\.items\.\w+\s*\(/ },
+    { scope: 'hawksearch:index', pattern: /\.hawksearch\.index\.(rebuild|status|wait|indexes|current)\s*\(/ },
+    { scope: 'hawksearch:index:manage', pattern: /\.hawksearch\.index\.(create|setCurrent|deleteIndex|rebuildAll)\s*\(/ },
+    { scope: 'hawksearch:recommendations', pattern: /\.hawksearch\.recommendations\s*\(/ },
+    { scope: 'storage', pattern: /\.storage\.(get|put|delete|list|batch|usage)\s*\(|\.storage\.files\.\w+\s*\(/ },
+    { scope: 'lambdas:invoke', pattern: /\.lambdas\.invoke\s*\(/ },
+    { scope: 'ai:invoke', pattern: /\.ai\.(generate|stream|info)\s*\(/ },
+    { scope: 'assistant', pattern: /\.assistant\.(ask|setContext)\s*\(/ },
+];
+
+const SOURCE = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.vue', '.svelte', '.html']);
+const SKIP = new Set(['node_modules', '.git', '.next', 'dist', 'out', 'build', 'coverage', '.turbo', '.vercel']);
+const MAX_FILES = 3000;
+const MAX_BYTES = 1024 * 1024;
+
+/** Source files of the project (not dependencies or build output), at most MAX_FILES. */
+async function sourceFiles(dir, found = []) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+        return found;
+    }
+    for (const entry of entries) {
+        if (found.length >= MAX_FILES) break;
+        if (entry.name.startsWith('.') && entry.name !== '.') continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP.has(entry.name)) await sourceFiles(full, found);
+        } else if (SOURCE.has(extname(entry.name))) {
+            found.push(full);
+        }
+    }
+    return found;
+}
+
+/**
+ * The scopes the code uses that `scopes` lacks: [{ scope, file, line }] (the first place each one is used), relative to
+ * `projectDir`.
+ */
+export async function missingScopes(projectDir, scopes = []) {
+    const declared = new Set(scopes);
+    const wanted = RULES.filter((rule) => !declared.has(rule.scope));
+    if (!wanted.length) return [];
+    const found = new Map();
+    for (const file of await sourceFiles(projectDir)) {
+        if (found.size === wanted.length) break;
+        let text;
+        try {
+            if ((await stat(file)).size > MAX_BYTES) continue;
+            text = await readFile(file, 'utf8');
+        } catch {
+            continue;
+        }
+        for (const rule of wanted) {
+            if (found.has(rule.scope)) continue;
+            const match = rule.pattern.exec(text);
+            if (match) {
+                const line = text.slice(0, match.index).split('\n').length;
+                found.set(rule.scope, { scope: rule.scope, file: relative(projectDir, file).split('\\').join('/'), line });
+            }
+        }
+    }
+    return [...found.values()];
+}
+
+/** The warning for what's missing (null: nothing). */
+export function describeMissingScopes(missing) {
+    if (!missing.length) return null;
+    const where = missing.map((m) => `${m.scope} (${m.file}:${m.line})`).join(', ');
+    return `The code uses ${where}, which "scopes" in hawk-app.json doesn't have: add ${missing.length === 1 ? 'it' : 'them'}, or those calls fail with 403 scope_missing.`;
+}

package/src/secrets.mjs

@@ -1,86 +1,86 @@
-import { SECRET_NAME } from './functions.mjs';
-import { promptHidden } from './login.mjs';
-
-/** The platform keeps each secret in a Standard-tier Parameter Store SecureString: at most 4 KB (UTF-8). */
-export const MAX_SECRET_BYTES = 4 * 1024;
-
-const USAGE = `Usage:
-  hawk-app secrets list
-  hawk-app secrets set <NAME> [--value-from-env <VAR>]
-  hawk-app secrets delete <NAME>`;
-
-/**
- * `hawk-app secrets …`: the app's function secrets, stored by the platform (never in the app or its versions).
- * Values are typed with hidden input (or read from an environment variable) and never printed. `client` is a
- * factory, so a usage mistake shows before any login check.
- */
-export async function secretsCommand({ client, manifest, sub, args = [], flags = {}, prompt = promptHidden, env = process.env, log = console.log }) {
-    const slug = manifest.slug;
-    switch (sub) {
-        case 'list': {
-            const { secrets = [] } = await client().listSecrets(slug);
-            const declared = declaredSecrets(manifest);
-            if (!secrets.length) log(`${slug} has no secrets yet. Set one with \`hawk-app secrets set <NAME>\`.`);
-            else {
-                log(`${secrets.length} secret${secrets.length === 1 ? '' : 's'} for ${slug} (values are never shown):`);
-                const width = Math.max(...secrets.map((s) => s.name.length));
-                for (const secret of secrets) {
-                    const users = declared.get(secret.name);
-                    log(`  ${secret.name.padEnd(width)}  ${secret.updatedAt ? `updated ${secret.updatedAt.slice(0, 16).replace('T', ' ')}` : ''}${users ? `  used by ${users.join(', ')}` : '  (not used by any function)'}`);
-                }
-            }
-            const missing = [...declared.keys()].filter((name) => !secrets.some((s) => s.name === name));
-            for (const name of missing) log(`! ${name} is declared by ${declared.get(name).join(', ')} but not set: calls fail with secret_missing until you set it.`);
-            return 0;
-        }
-
-        case 'set': {
-            const name = checkName(args[0]);
-            let value;
-            const from = flags['value-from-env'];
-            if (from !== undefined) {
-                if (typeof from !== 'string' || !from) throw new Error('--value-from-env needs the name of an environment variable.');
-                value = env[from];
-                if (value === undefined || value === '') throw new Error(`Environment variable ${from} is not set (or empty).`);
-            } else {
-                value = await prompt(`Value for ${name} (input hidden): `, {
-                    notInteractive: `\`hawk-app secrets set\` needs an interactive terminal to type the value. In CI, pass --value-from-env <VAR>.`,
-                });
-                if (!value) throw new Error('No value entered; nothing was changed.');
-            }
-            if (Buffer.byteLength(value, 'utf8') > MAX_SECRET_BYTES) throw new Error(`The value is larger than ${MAX_SECRET_BYTES / 1024} KB.`);
-            await client().setSecret(slug, name, value);
-            log(`✔ Set ${name} for ${slug}. It applies to every version at once.`);
-            if (!declaredSecrets(manifest).has(name)) log(`! No function in hawk-app.json declares ${name}: add it to a function's "secrets" to receive it as ctx.secrets.${name}.`);
-            return 0;
-        }
-
-        case 'delete': {
-            const name = checkName(args[0]);
-            await client().deleteSecret(slug, name);
-            log(`✔ Deleted ${name} for ${slug}.`);
-            const users = declaredSecrets(manifest).get(name);
-            if (users) log(`! ${users.join(', ')} still declare${users.length === 1 ? 's' : ''} ${name}: calls fail with secret_missing until it's set again.`);
-            return 0;
-        }
-
-        default:
-            throw new Error(sub ? `Unknown secrets command "${sub}".\n${USAGE}` : USAGE);
-    }
-}
-
-function checkName(name) {
-    if (!name) throw new Error(USAGE);
-    if (!SECRET_NAME.test(name)) throw new Error(`"${name}" is not a valid secret name: UPPER_SNAKE_CASE, a letter first, up to 64 characters (e.g. FEED_API_KEY).`);
-    return name;
-}
-
-/** Secret name → the functions in the manifest that declare it. */
-function declaredSecrets(manifest) {
-    const map = new Map();
-    const functions = manifest.functions && typeof manifest.functions === 'object' ? manifest.functions : {};
-    for (const [fn, config] of Object.entries(functions)) {
-        for (const secret of Array.isArray(config?.secrets) ? config.secrets : []) map.set(secret, [...(map.get(secret) ?? []), fn]);
-    }
-    return map;
-}
+import { SECRET_NAME } from './functions.mjs';
+import { promptHidden } from './login.mjs';
+
+/** The platform keeps each secret in a Standard-tier Parameter Store SecureString: at most 4 KB (UTF-8). */
+export const MAX_SECRET_BYTES = 4 * 1024;
+
+const USAGE = `Usage:
+  hawk-app secrets list
+  hawk-app secrets set <NAME> [--value-from-env <VAR>]
+  hawk-app secrets delete <NAME>`;
+
+/**
+ * `hawk-app secrets …`: the app's function secrets, stored by the platform (never in the app or its versions).
+ * Values are typed with hidden input (or read from an environment variable) and never printed. `client` is a
+ * factory, so a usage mistake shows before any login check.
+ */
+export async function secretsCommand({ client, manifest, sub, args = [], flags = {}, prompt = promptHidden, env = process.env, log = console.log }) {
+    const slug = manifest.slug;
+    switch (sub) {
+        case 'list': {
+            const { secrets = [] } = await client().listSecrets(slug);
+            const declared = declaredSecrets(manifest);
+            if (!secrets.length) log(`${slug} has no secrets yet. Set one with \`hawk-app secrets set <NAME>\`.`);
+            else {
+                log(`${secrets.length} secret${secrets.length === 1 ? '' : 's'} for ${slug} (values are never shown):`);
+                const width = Math.max(...secrets.map((s) => s.name.length));
+                for (const secret of secrets) {
+                    const users = declared.get(secret.name);
+                    log(`  ${secret.name.padEnd(width)}  ${secret.updatedAt ? `updated ${secret.updatedAt.slice(0, 16).replace('T', ' ')}` : ''}${users ? `  used by ${users.join(', ')}` : '  (not used by any function)'}`);
+                }
+            }
+            const missing = [...declared.keys()].filter((name) => !secrets.some((s) => s.name === name));
+            for (const name of missing) log(`! ${name} is declared by ${declared.get(name).join(', ')} but not set: calls fail with secret_missing until you set it.`);
+            return 0;
+        }
+
+        case 'set': {
+            const name = checkName(args[0]);
+            let value;
+            const from = flags['value-from-env'];
+            if (from !== undefined) {
+                if (typeof from !== 'string' || !from) throw new Error('--value-from-env needs the name of an environment variable.');
+                value = env[from];
+                if (value === undefined || value === '') throw new Error(`Environment variable ${from} is not set (or empty).`);
+            } else {
+                value = await prompt(`Value for ${name} (input hidden): `, {
+                    notInteractive: `\`hawk-app secrets set\` needs an interactive terminal to type the value. In CI, pass --value-from-env <VAR>.`,
+                });
+                if (!value) throw new Error('No value entered; nothing was changed.');
+            }
+            if (Buffer.byteLength(value, 'utf8') > MAX_SECRET_BYTES) throw new Error(`The value is larger than ${MAX_SECRET_BYTES / 1024} KB.`);
+            await client().setSecret(slug, name, value);
+            log(`✔ Set ${name} for ${slug}. It applies to every version at once.`);
+            if (!declaredSecrets(manifest).has(name)) log(`! No function in hawk-app.json declares ${name}: add it to a function's "secrets" to receive it as ctx.secrets.${name}.`);
+            return 0;
+        }
+
+        case 'delete': {
+            const name = checkName(args[0]);
+            await client().deleteSecret(slug, name);
+            log(`✔ Deleted ${name} for ${slug}.`);
+            const users = declaredSecrets(manifest).get(name);
+            if (users) log(`! ${users.join(', ')} still declare${users.length === 1 ? 's' : ''} ${name}: calls fail with secret_missing until it's set again.`);
+            return 0;
+        }
+
+        default:
+            throw new Error(sub ? `Unknown secrets command "${sub}".\n${USAGE}` : USAGE);
+    }
+}
+
+function checkName(name) {
+    if (!name) throw new Error(USAGE);
+    if (!SECRET_NAME.test(name)) throw new Error(`"${name}" is not a valid secret name: UPPER_SNAKE_CASE, a letter first, up to 64 characters (e.g. FEED_API_KEY).`);
+    return name;
+}
+
+/** Secret name → the functions in the manifest that declare it. */
+function declaredSecrets(manifest) {
+    const map = new Map();
+    const functions = manifest.functions && typeof manifest.functions === 'object' ? manifest.functions : {};
+    for (const [fn, config] of Object.entries(functions)) {
+        for (const secret of Array.isArray(config?.secrets) ? config.secrets : []) map.set(secret, [...(map.get(secret) ?? []), fn]);
+    }
+    return map;
+}

package/src/slug-guard.mjs

@@ -1,80 +1,80 @@
-// Keeps two developers from working on one app by accident. Apps belong to a publisher (a team), and every person on
-// the team can register and deploy any of its apps, so a reused slug would silently mix two codebases into one app.
-//   - create / init: refuse a slug that's already taken (unless --yes).
-//   - register / deploy: when someone else's key made the app's last change, ask before going on (--yes skips it; a
-//     pipeline, with no terminal to ask in, gets a warning and goes on).
-import { createInterface } from 'node:readline';
-
-/**
- * What the platform says about a slug for the caller's key: free (404), another publisher's (409 slug_owned), or this
- * publisher's app with its last change. Null when it can't tell (not logged in, platform unreachable, other errors).
- */
-export async function slugStatus(client, slug) {
-    try {
-        const app = await client.status(slug);
-        return { state: 'taken', app };
-    } catch (error) {
-        if (error.status === 404) return { state: 'free' };
-        if (error.status === 409) return { state: 'other' };
-        return null;
-    }
-}
-
-const describeChange = (last) => {
-    const who = last.name || last.keyId || 'a shared key';
-    const when = last.at ? new Date(last.at).toLocaleString() : 'earlier';
-    return `${last.kind === 'deploy' ? 'deployed' : 'registered'} by ${who} on ${when}`;
-};
-
-/** create / init: throws when the slug is taken; logs a note when it couldn't check. */
-export async function checkNewSlug({ client, slug, yes = false, log = console.log }) {
-    if (!client) {
-        log(`  (Not logged in, so "${slug}" wasn't checked. \`hawk-app register\` will tell you if it's taken.)`);
-        return;
-    }
-    const status = await slugStatus(client, slug);
-    if (!status) {
-        log(`  (Couldn't check whether "${slug}" is free; \`hawk-app register\` will tell you if it's taken.)`);
-        return;
-    }
-    if (status.state === 'other') {
-        throw new Error(`"${slug}" belongs to another publisher. Pick another name (the folder name, or --slug).`);
-    }
-    if (status.state === 'taken' && !yes) {
-        const last = status.app.lastChange;
-        throw new Error(
-            `"${slug}" is already an app${last ? `, last ${describeChange(last)}` : ''}. Pick another name, or work in that app's own repository.\n` +
-                '  To set up this folder for that existing app anyway, add --yes.',
-        );
-    }
-}
-
-/** Asks a yes/no question on the terminal; null when there is no terminal to ask in. */
-export function askYesNo(question, { input = process.stdin, output = process.stdout } = {}) {
-    if (!input.isTTY) return Promise.resolve(null);
-    return new Promise((resolve) => {
-        const rl = createInterface({ input, output });
-        rl.question(`${question} (y/N) `, (answer) => {
-            rl.close();
-            resolve(/^y(es)?$/i.test(answer.trim()));
-        });
-    });
-}
-
-/**
- * register / deploy: when the app's last change was made with someone else's key, asks before going on. Throws
- * "Cancelled." on no; with no terminal (CI) it warns and goes on; --yes goes on quietly.
- */
-export async function confirmTakeover({ client, slug, action, yes = false, confirm = askYesNo, log = console.log }) {
-    const status = await slugStatus(client, slug);
-    const last = status?.state === 'taken' ? status.app.lastChange : null;
-    if (!last || last.yours || yes) return;
-
-    const message = `"${slug}" was last ${describeChange(last)}.`;
-    const answer = await confirm(`${message} ${action === 'deploy' ? 'Deploy a new version of it' : 'Register your hawk-app.json over it'}?`);
-    if (answer === null) {
-        log(`! ${message} Going on (no terminal to ask; add --yes to silence this).`);
-        return;
-    }
-    if (!answer) throw new Error('Cancelled. Nothing was changed.');
-}
+// Keeps two developers from working on one app by accident. Apps belong to a publisher (a team), and every person on
+// the team can register and deploy any of its apps, so a reused slug would silently mix two codebases into one app.
+//   - create / init: refuse a slug that's already taken (unless --yes).
+//   - register / deploy: when someone else's key made the app's last change, ask before going on (--yes skips it; a
+//     pipeline, with no terminal to ask in, gets a warning and goes on).
+import { createInterface } from 'node:readline';
+
+/**
+ * What the platform says about a slug for the caller's key: free (404), another publisher's (409 slug_owned), or this
+ * publisher's app with its last change. Null when it can't tell (not logged in, platform unreachable, other errors).
+ */
+export async function slugStatus(client, slug) {
+    try {
+        const app = await client.status(slug);
+        return { state: 'taken', app };
+    } catch (error) {
+        if (error.status === 404) return { state: 'free' };
+        if (error.status === 409) return { state: 'other' };
+        return null;
+    }
+}
+
+const describeChange = (last) => {
+    const who = last.name || last.keyId || 'a shared key';
+    const when = last.at ? new Date(last.at).toLocaleString() : 'earlier';
+    return `${last.kind === 'deploy' ? 'deployed' : 'registered'} by ${who} on ${when}`;
+};
+
+/** create / init: throws when the slug is taken; logs a note when it couldn't check. */
+export async function checkNewSlug({ client, slug, yes = false, log = console.log }) {
+    if (!client) {
+        log(`  (Not logged in, so "${slug}" wasn't checked. \`hawk-app register\` will tell you if it's taken.)`);
+        return;
+    }
+    const status = await slugStatus(client, slug);
+    if (!status) {
+        log(`  (Couldn't check whether "${slug}" is free; \`hawk-app register\` will tell you if it's taken.)`);
+        return;
+    }
+    if (status.state === 'other') {
+        throw new Error(`"${slug}" belongs to another publisher. Pick another name (the folder name, or --slug).`);
+    }
+    if (status.state === 'taken' && !yes) {
+        const last = status.app.lastChange;
+        throw new Error(
+            `"${slug}" is already an app${last ? `, last ${describeChange(last)}` : ''}. Pick another name, or work in that app's own repository.\n` +
+                '  To set up this folder for that existing app anyway, add --yes.',
+        );
+    }
+}
+
+/** Asks a yes/no question on the terminal; null when there is no terminal to ask in. */
+export function askYesNo(question, { input = process.stdin, output = process.stdout } = {}) {
+    if (!input.isTTY) return Promise.resolve(null);
+    return new Promise((resolve) => {
+        const rl = createInterface({ input, output });
+        rl.question(`${question} (y/N) `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+
+/**
+ * register / deploy: when the app's last change was made with someone else's key, asks before going on. Throws
+ * "Cancelled." on no; with no terminal (CI) it warns and goes on; --yes goes on quietly.
+ */
+export async function confirmTakeover({ client, slug, action, yes = false, confirm = askYesNo, log = console.log }) {
+    const status = await slugStatus(client, slug);
+    const last = status?.state === 'taken' ? status.app.lastChange : null;
+    if (!last || last.yours || yes) return;
+
+    const message = `"${slug}" was last ${describeChange(last)}.`;
+    const answer = await confirm(`${message} ${action === 'deploy' ? 'Deploy a new version of it' : 'Register your hawk-app.json over it'}?`);
+    if (answer === null) {
+        log(`! ${message} Going on (no terminal to ask; add --yes to silence this).`);
+        return;
+    }
+    if (!answer) throw new Error('Cancelled. Nothing was changed.');
+}