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

package/src/doctor.mjs

@@ -1,176 +1,176 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
-import { describePlatform, PLATFORMS, resolveSettings } from './env.mjs';
-import { checkKey } from './login.mjs';
-import { loadManifest, validateManifest } from './manifest.mjs';
-import { checkProject } from './project-checks.mjs';
-import { describeMissingScopes, missingScopes } from './scope-check.mjs';
-import { upgradeHint } from './upgrade.mjs';
-import { openBrowser } from './sso.mjs';
-
-/** The HawkSearch dashboard of each platform environment (where apps are reviewed and opened). */
-export const DASHBOARDS = {
-    dev: 'https://e360.dev.bridgeline.com',
-    prod: 'https://app.hawksearch.com',
-};
-
-const envOf = (url) => Object.entries(PLATFORMS).find(([, u]) => u.replace(/\/+$/, '') === String(url).replace(/\/+$/, ''))?.[0];
-
-/** The app's page in HawkSearch (optionally shown as an alias's clients see it); null for an unknown platform. */
-export function appUrl(platformUrl, slug, alias) {
-    const dashboard = DASHBOARDS[envOf(platformUrl)];
-    if (!dashboard) return null;
-    return `${dashboard}/admin/apps/${encodeURIComponent(slug)}${alias ? `?alias=${encodeURIComponent(alias)}` : ''}`;
-}
-
-/** The developer docs (built from the hawk-apps repo's markdown; sign in with a Bridgeline account). */
-export const DOCS_URL = 'https://developers.hawksearchapps.com';
-
-/**
- * `hawk-app docs <topic>`: the page for each topic. Developers' topics open the developer docs (a feature's section of
- * the bridge reference); `platform` opens the engineering docs, which the site keeps out of its navigation and search.
- */
-export const DOCS_TOPICS = {
-    start: '/start/',
-    claude: '/start/with-claude/',
-    concepts: '/concepts/how-it-works/',
-    versions: '/concepts/versions-and-aliases/',
-    aliases: '/concepts/versions-and-aliases/',
-    bridge: '/reference/bridge/',
-    api: '/reference/api/',
-    cli: '/reference/cli/',
-    commands: '/reference/cli-commands/',
-    manifest: '/reference/hawk-app-json/',
-    'hawk-app.json': '/reference/hawk-app-json/',
-    queries: '/reference/bridge/#custom-data-queries-dataread',
-    data: '/reference/bridge/#data',
-    functions: '/reference/bridge/#functions-functionsinvoke',
-    email: '/reference/bridge/#email-emailsend',
-    storage: '/reference/bridge/#storage-storage',
-    ai: '/reference/bridge/#ai-aiinvoke',
-    search: '/reference/bridge/#hawksearch-search-hawksearchsearch',
-    review: '/reference/cli/#review-in-hawksearch',
-    'whats-new': '/whats-new/cli/',
-    platform: '/engineering/',
-};
-
-/** `hawk-app docs [topic]`: opens the developer docs (a topic's page), and prints the link. */
-export async function docsCommand({ topic, openUrl = openBrowser, log = console.log }) {
-    const key = typeof topic === 'string' ? topic.toLowerCase() : undefined;
-    if (key !== undefined && !(key in DOCS_TOPICS)) {
-        throw new Error(`No docs topic "${topic}". Topics: ${Object.keys(DOCS_TOPICS).join(', ')}.`);
-    }
-    const url = `${DOCS_URL}${key ? DOCS_TOPICS[key] : '/'}`;
-    log(`Hawk Apps developer docs: ${url}`);
-    log('  Sign in with your Bridgeline account. The site has search (top of every page).');
-    try {
-        await openUrl(url);
-    } catch {
-        // No browser (CI, SSH): the link above is enough.
-    }
-    return 0;
-}
-
-/** `hawk-app open [--alias <name>]`: the app's page in HawkSearch, to review it, submit it for approval, or try an alias. */
-export async function openCommand({ manifestFile, flags = {}, openUrl = openBrowser, log = console.log }) {
-    const manifest = await loadManifest(manifestFile);
-    const { url } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env, dir: dirname(resolve(manifestFile)) });
-    const alias = typeof flags.alias === 'string' ? flags.alias : undefined;
-    const page = appUrl(url, manifest.slug, alias);
-    if (!page) throw new Error(`No HawkSearch dashboard is known for ${describePlatform(url)}. Open the Apps page there and pick ${manifest.slug}.`);
-    log(`${manifest.slug} in HawkSearch${alias ? ` (as ${alias}'s clients see it)` : ''}: ${page}`);
-    log('  Bridgeline staff: review it there and submit it for approval (More review actions). Clients\' users see it once it\'s released.');
-    try {
-        await openUrl(page);
-    } catch {
-        // No browser (CI, SSH): the link above is enough.
-    }
-    return 0;
-}
-
-/**
- * `hawk-app doctor`: everything a developer needs working, in one go: Node, the login and platform, hawk-app.json, the
- * project (bridge, build script, template), scopes the code uses, the app on the platform and the MCP config. Each line
- * says what to do when it isn't right. Exit 1 when something must be fixed.
- */
-export async function doctorCommand({ manifestFile, flags = {}, fetchImpl = fetch, log = console.log, nodeVersion = process.versions.node }) {
-    let failed = 0;
-    const ok = (text) => log(`✔ ${text}`);
-    const warn = (text) => log(`! ${text}`);
-    const fail = (text) => {
-        failed += 1;
-        log(`✖ ${text}`);
-    };
-
-    // Node.
-    const major = Number(String(nodeVersion).split('.')[0]);
-    if (major >= 20) ok(`Node ${nodeVersion}`);
-    else if (major >= 18) warn(`Node ${nodeVersion}: works, but the templates are tested on Node 20 or later.`);
-    else fail(`Node ${nodeVersion}: install Node 20 or later (https://nodejs.org).`);
-
-    // Login and platform.
-    const projectDir = dirname(resolve(manifestFile));
-    const settings = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env, dir: projectDir });
-    if (!settings.key) {
-        fail(`Not logged in to ${describePlatform(settings.url)}: run \`npx hawk-app sso\` (Bridgeline account) once on this machine.`);
-    } else {
-        const check = await checkKey(settings.url, settings.key, fetchImpl);
-        if (check.ok) ok(`Logged in to ${describePlatform(settings.url)} (key from ${settings.keySource})`);
-        else fail(`${check.reason} Run \`npx hawk-app sso\` again.`);
-    }
-
-    // The app.
-    if (!existsSync(manifestFile)) {
-        fail(`No ${manifestFile} here: run this in the app's folder, or start one with \`npx hawk-app create <folder>\` (\`init\` for an existing project).`);
-        return failed ? 1 : 0;
-    }
-    let manifest;
-    try {
-        manifest = await loadManifest(manifestFile);
-    } catch (error) {
-        fail(error.message);
-        return 1;
-    }
-    const checked = validateManifest(manifest);
-    if (checked.errors.length) fail(`${manifestFile}: ${checked.errors.join(' ')} (details: npx hawk-app validate)`);
-    else ok(`${manifestFile}: ${manifest.slug}`);
-    for (const warning of checked.warnings) warn(warning);
-
-    const project = await checkProject(projectDir);
-    for (const warning of project.warnings) warn(warning);
-    if (!project.warnings.length) ok('Project: the bridge and a build script are set up');
-    try {
-        const hint = upgradeHint(projectDir, manifest);
-        if (hint) warn(hint.replace(/^! /, ''));
-        else ok('Up to date with its template');
-    } catch {
-        // An app that follows no template: nothing to compare.
-    }
-    const scopes = describeMissingScopes(await missingScopes(projectDir, manifest.scopes));
-    if (scopes) warn(scopes);
-    else ok('Scopes: hawk-app.json has the ones the code uses');
-
-    // The app on the platform.
-    if (settings.key) {
-        try {
-            const response = await fetchImpl(`${settings.url}/publish/apps/${encodeURIComponent(manifest.slug)}`, { headers: { Authorization: `PublisherKey ${settings.key}` } });
-            if (response.status === 404) warn(`${manifest.slug} isn't on ${describePlatform(settings.url)} yet: \`npm run app:dev -- --client <id>\` or \`npm run app:deploy\` registers it.`);
-            else if (response.status === 409) fail(`${manifest.slug} belongs to another team: pick another slug in ${manifestFile}.`);
-            else if (response.ok) {
-                const app = await response.json();
-                ok(`On the platform: ${app.status === 'Live' && app.liveVersion ? `released v${app.liveVersion}` : 'not released yet'} (npx hawk-app status)`);
-            }
-        } catch {
-            // Already reported with the login check.
-        }
-    }
-
-    // AI assistants.
-    const mcp = join(projectDir, '.mcp.json');
-    if (existsSync(mcp) && readFileSync(mcp, 'utf8').includes('hawk-apps')) ok('MCP server set up for AI assistants (.mcp.json)');
-    else warn('No MCP config for AI assistants: `npx hawk-app upgrade --yes` adds .mcp.json and .vscode/mcp.json.');
-
-    log(failed ? `\n${failed} thing${failed === 1 ? '' : 's'} to fix above.` : '\nAll set.');
-    log(`Docs: ${DOCS_URL} (npx hawk-app docs)`);
-    return failed ? 1 : 0;
-}
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { describePlatform, PLATFORMS, resolveSettings } from './env.mjs';
+import { checkKey } from './login.mjs';
+import { loadManifest, validateManifest } from './manifest.mjs';
+import { checkProject } from './project-checks.mjs';
+import { describeMissingScopes, missingScopes } from './scope-check.mjs';
+import { upgradeHint } from './upgrade.mjs';
+import { openBrowser } from './sso.mjs';
+
+/** The HawkSearch dashboard of each platform environment (where apps are reviewed and opened). */
+export const DASHBOARDS = {
+    dev: 'https://e360.dev.bridgeline.com',
+    prod: 'https://app.hawksearch.com',
+};
+
+const envOf = (url) => Object.entries(PLATFORMS).find(([, u]) => u.replace(/\/+$/, '') === String(url).replace(/\/+$/, ''))?.[0];
+
+/** The app's page in HawkSearch (optionally shown as an alias's clients see it); null for an unknown platform. */
+export function appUrl(platformUrl, slug, alias) {
+    const dashboard = DASHBOARDS[envOf(platformUrl)];
+    if (!dashboard) return null;
+    return `${dashboard}/admin/apps/${encodeURIComponent(slug)}${alias ? `?alias=${encodeURIComponent(alias)}` : ''}`;
+}
+
+/** The developer docs (built from the hawk-apps repo's markdown; sign in with a Bridgeline account). */
+export const DOCS_URL = 'https://developers.hawksearchapps.com';
+
+/**
+ * `hawk-app docs <topic>`: the page for each topic. Developers' topics open the developer docs (a feature's section of
+ * the bridge reference); `platform` opens the engineering docs, which the site keeps out of its navigation and search.
+ */
+export const DOCS_TOPICS = {
+    start: '/start/',
+    claude: '/start/with-claude/',
+    concepts: '/concepts/how-it-works/',
+    versions: '/concepts/versions-and-aliases/',
+    aliases: '/concepts/versions-and-aliases/',
+    bridge: '/reference/bridge/',
+    api: '/reference/api/',
+    cli: '/reference/cli/',
+    commands: '/reference/cli-commands/',
+    manifest: '/reference/hawk-app-json/',
+    'hawk-app.json': '/reference/hawk-app-json/',
+    queries: '/reference/bridge/#custom-data-queries-dataread',
+    data: '/reference/bridge/#data',
+    functions: '/reference/bridge/#functions-functionsinvoke',
+    email: '/reference/bridge/#email-emailsend',
+    storage: '/reference/bridge/#storage-storage',
+    ai: '/reference/bridge/#ai-aiinvoke',
+    search: '/reference/bridge/#hawksearch-search-hawksearchsearch',
+    review: '/reference/cli/#review-in-hawksearch',
+    'whats-new': '/whats-new/cli/',
+    platform: '/engineering/',
+};
+
+/** `hawk-app docs [topic]`: opens the developer docs (a topic's page), and prints the link. */
+export async function docsCommand({ topic, openUrl = openBrowser, log = console.log }) {
+    const key = typeof topic === 'string' ? topic.toLowerCase() : undefined;
+    if (key !== undefined && !(key in DOCS_TOPICS)) {
+        throw new Error(`No docs topic "${topic}". Topics: ${Object.keys(DOCS_TOPICS).join(', ')}.`);
+    }
+    const url = `${DOCS_URL}${key ? DOCS_TOPICS[key] : '/'}`;
+    log(`Hawk Apps developer docs: ${url}`);
+    log('  Sign in with your Bridgeline account. The site has search (top of every page).');
+    try {
+        await openUrl(url);
+    } catch {
+        // No browser (CI, SSH): the link above is enough.
+    }
+    return 0;
+}
+
+/** `hawk-app open [--alias <name>]`: the app's page in HawkSearch, to review it, submit it for approval, or try an alias. */
+export async function openCommand({ manifestFile, flags = {}, openUrl = openBrowser, log = console.log }) {
+    const manifest = await loadManifest(manifestFile);
+    const { url } = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env, dir: dirname(resolve(manifestFile)) });
+    const alias = typeof flags.alias === 'string' ? flags.alias : undefined;
+    const page = appUrl(url, manifest.slug, alias);
+    if (!page) throw new Error(`No HawkSearch dashboard is known for ${describePlatform(url)}. Open the Apps page there and pick ${manifest.slug}.`);
+    log(`${manifest.slug} in HawkSearch${alias ? ` (as ${alias}'s clients see it)` : ''}: ${page}`);
+    log('  Bridgeline staff: review it there and submit it for approval (More review actions). Clients\' users see it once it\'s released.');
+    try {
+        await openUrl(page);
+    } catch {
+        // No browser (CI, SSH): the link above is enough.
+    }
+    return 0;
+}
+
+/**
+ * `hawk-app doctor`: everything a developer needs working, in one go: Node, the login and platform, hawk-app.json, the
+ * project (bridge, build script, template), scopes the code uses, the app on the platform and the MCP config. Each line
+ * says what to do when it isn't right. Exit 1 when something must be fixed.
+ */
+export async function doctorCommand({ manifestFile, flags = {}, fetchImpl = fetch, log = console.log, nodeVersion = process.versions.node }) {
+    let failed = 0;
+    const ok = (text) => log(`✔ ${text}`);
+    const warn = (text) => log(`! ${text}`);
+    const fail = (text) => {
+        failed += 1;
+        log(`✖ ${text}`);
+    };
+
+    // Node.
+    const major = Number(String(nodeVersion).split('.')[0]);
+    if (major >= 20) ok(`Node ${nodeVersion}`);
+    else if (major >= 18) warn(`Node ${nodeVersion}: works, but the templates are tested on Node 20 or later.`);
+    else fail(`Node ${nodeVersion}: install Node 20 or later (https://nodejs.org).`);
+
+    // Login and platform.
+    const projectDir = dirname(resolve(manifestFile));
+    const settings = resolveSettings({ flagPlatform: flags.platform, flagEnv: flags.env, dir: projectDir });
+    if (!settings.key) {
+        fail(`Not logged in to ${describePlatform(settings.url)}: run \`npx hawk-app sso\` (Bridgeline account) once on this machine.`);
+    } else {
+        const check = await checkKey(settings.url, settings.key, fetchImpl);
+        if (check.ok) ok(`Logged in to ${describePlatform(settings.url)} (key from ${settings.keySource})`);
+        else fail(`${check.reason} Run \`npx hawk-app sso\` again.`);
+    }
+
+    // The app.
+    if (!existsSync(manifestFile)) {
+        fail(`No ${manifestFile} here: run this in the app's folder, or start one with \`npx hawk-app create <folder>\` (\`init\` for an existing project).`);
+        return failed ? 1 : 0;
+    }
+    let manifest;
+    try {
+        manifest = await loadManifest(manifestFile);
+    } catch (error) {
+        fail(error.message);
+        return 1;
+    }
+    const checked = validateManifest(manifest);
+    if (checked.errors.length) fail(`${manifestFile}: ${checked.errors.join(' ')} (details: npx hawk-app validate)`);
+    else ok(`${manifestFile}: ${manifest.slug}`);
+    for (const warning of checked.warnings) warn(warning);
+
+    const project = await checkProject(projectDir);
+    for (const warning of project.warnings) warn(warning);
+    if (!project.warnings.length) ok('Project: the bridge and a build script are set up');
+    try {
+        const hint = upgradeHint(projectDir, manifest);
+        if (hint) warn(hint.replace(/^! /, ''));
+        else ok('Up to date with its template');
+    } catch {
+        // An app that follows no template: nothing to compare.
+    }
+    const scopes = describeMissingScopes(await missingScopes(projectDir, manifest.scopes));
+    if (scopes) warn(scopes);
+    else ok('Scopes: hawk-app.json has the ones the code uses');
+
+    // The app on the platform.
+    if (settings.key) {
+        try {
+            const response = await fetchImpl(`${settings.url}/publish/apps/${encodeURIComponent(manifest.slug)}`, { headers: { Authorization: `PublisherKey ${settings.key}` } });
+            if (response.status === 404) warn(`${manifest.slug} isn't on ${describePlatform(settings.url)} yet: \`npm run app:dev -- --client <id>\` or \`npm run app:deploy\` registers it.`);
+            else if (response.status === 409) fail(`${manifest.slug} belongs to another team: pick another slug in ${manifestFile}.`);
+            else if (response.ok) {
+                const app = await response.json();
+                ok(`On the platform: ${app.status === 'Live' && app.liveVersion ? `released v${app.liveVersion}` : 'not released yet'} (npx hawk-app status)`);
+            }
+        } catch {
+            // Already reported with the login check.
+        }
+    }
+
+    // AI assistants.
+    const mcp = join(projectDir, '.mcp.json');
+    if (existsSync(mcp) && readFileSync(mcp, 'utf8').includes('hawk-apps')) ok('MCP server set up for AI assistants (.mcp.json)');
+    else warn('No MCP config for AI assistants: `npx hawk-app upgrade --yes` adds .mcp.json and .vscode/mcp.json.');
+
+    log(failed ? `\n${failed} thing${failed === 1 ? '' : 's'} to fix above.` : '\nAll set.');
+    log(`Docs: ${DOCS_URL} (npx hawk-app docs)`);
+    return failed ? 1 : 0;
+}

package/src/env.mjs

@@ -1,140 +1,140 @@
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { credentialsPath, normalizeUrl, readCredentials } from './credentials.mjs';
-
-export const ENV_FILES = ['.env.local', '.env'];
-
-/** The platform of each environment (`--env` / HAWK_APPS_ENV). */
-export const PLATFORMS = {
-    dev: 'https://api-dev.hawksearchapps.com',
-    prod: 'https://api.hawksearchapps.com',
-};
-
-/** Dev, unless a command, the environment or the project says otherwise: prod is never a default. */
-export const DEFAULT_PLATFORM_URL = PLATFORMS.dev;
-
-/** The URL of an environment name; throws for an unknown one (a typo must not fall back to dev or prod). */
-export function platformForEnv(name, source) {
-    if (!name) return undefined;
-    const url = PLATFORMS[String(name).trim().toLowerCase()];
-    if (!url) throw new Error(`Unknown environment "${name}" (${source}): use ${Object.keys(PLATFORMS).join(' or ')}.`);
-    return url;
-}
-
-/** "prod (https://…)" for a known platform, else the URL. */
-export function describePlatform(url) {
-    const name = Object.entries(PLATFORMS).find(([, u]) => normalizeUrl(u) === normalizeUrl(url))?.[0];
-    return name ? `${name} (${url})` : String(url);
-}
-const PREFIX = 'HAWK_APPS_';
-
-/** Parses KEY=VALUE lines; supports comments, blank lines, `export KEY=...` and single/double quotes. */
-export function parseEnv(text) {
-    const values = {};
-    for (const raw of text.split(/\r?\n/)) {
-        const line = raw.trim();
-        if (!line || line.startsWith('#')) continue;
-        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
-        if (!match) continue;
-        let value = match[2].trim();
-        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-            value = value.slice(1, -1);
-        } else {
-            value = value.replace(/\s+#.*$/, '');
-        }
-        values[match[1]] = value;
-    }
-    return values;
-}
-
-/**
- * Loads HAWK_APPS_* settings from .env.local / .env in `dir`. Variables already set in the environment win,
- * so CI secrets always take precedence. Only HAWK_APPS_* keys are applied.
- * @returns {{ loaded: string[], warnings: string[] }}
- */
-export function loadEnv(dir = process.cwd(), env = process.env, isIgnored = gitIgnored) {
-    const loaded = [];
-    const warnings = [];
-    for (const file of ENV_FILES) {
-        const path = join(dir, file);
-        if (!existsSync(path)) continue;
-        const values = parseEnv(readFileSync(path, 'utf8'));
-        for (const [key, value] of Object.entries(values)) {
-            if (!key.startsWith(PREFIX) || !value || env[key] !== undefined) continue;
-            env[key] = value;
-            loaded.push(`${key} (${file})`);
-        }
-        if (values.HAWK_APPS_PUBLISHER_KEY && isIgnored(dir, file) === false) {
-            warnings.push(`${file} contains your publisher key but is not git-ignored. Add it to .gitignore so the key is never committed.`);
-        }
-    }
-    return { loaded, warnings };
-}
-
-/**
- * Where the platform URL and publisher key come from, highest priority first:
- *   URL: --platform / --env, HAWK_APPS_PLATFORM_URL / HAWK_APPS_ENV, project .env.local / .env (the same two), dev.
- *        `hawk-app login` never changes it: logging in to prod doesn't make later commands use prod.
- *   Key: HAWK_APPS_PUBLISHER_KEY, project .env.local / .env, the key saved by `hawk-app login` for that URL.
- */
-// credentialsFile defaults to this machine's `hawk-app login` file, so every command sees the saved login (not just whoami).
-export function resolveSettings({ flagPlatform, flagEnv, env = process.env, dir = process.cwd(), credentialsFile = credentialsPath(env) } = {}) {
-    if (flagPlatform && flagEnv) throw new Error('Use --env or --platform, not both.');
-    const fileValues = {};
-    const fileSource = {};
-    for (const file of [...ENV_FILES].reverse()) {
-        const path = join(dir, file);
-        if (!existsSync(path)) continue;
-        for (const [key, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
-            if (key.startsWith(PREFIX) && value) {
-                fileValues[key] = value;
-                fileSource[key] = file;
-            }
-        }
-    }
-    const credentials = readCredentials(credentialsFile);
-
-    const [url, urlSource] = first([
-        [flagPlatform, '--platform'],
-        [platformForEnv(flagEnv, '--env'), '--env'],
-        [env.HAWK_APPS_PLATFORM_URL, 'environment'],
-        [platformForEnv(env.HAWK_APPS_ENV, 'HAWK_APPS_ENV'), 'HAWK_APPS_ENV'],
-        [fileValues.HAWK_APPS_PLATFORM_URL, fileSource.HAWK_APPS_PLATFORM_URL],
-        [platformForEnv(fileValues.HAWK_APPS_ENV, fileSource.HAWK_APPS_ENV), fileSource.HAWK_APPS_ENV],
-        [DEFAULT_PLATFORM_URL, 'default (dev)'],
-    ]);
-    const platform = normalizeUrl(url);
-    const [key, keySource] = first([
-        [env.HAWK_APPS_PUBLISHER_KEY, 'environment'],
-        [fileValues.HAWK_APPS_PUBLISHER_KEY, fileSource.HAWK_APPS_PUBLISHER_KEY],
-        [credentials.platforms[platform]?.publisherKey, credentialsFile],
-    ]);
-    return { url: platform, urlSource, key, keySource, credentialsFile };
-}
-
-function first(candidates) {
-    return candidates.find(([value]) => value) ?? [undefined, undefined];
-}
-
-/** true / false inside a git repo; undefined when git isn't available or this isn't a repo. */
-function gitIgnored(dir, file) {
-    const result = spawnSync('git', ['check-ignore', '-q', file], { cwd: dir, stdio: 'ignore' });
-    if (result.error || result.status === 128) return undefined;
-    return result.status === 0;
-}
-
-export const ENV_EXAMPLE = `# Optional per-project overrides. Normally you don't need this file: run \`npx hawk-app sso\` once per machine.
-# To override for this project only, copy to .env.local (git-ignored) and uncomment.
-# Environment variables (e.g. CI secrets) take precedence over both.
-
-# The environment this project deploys to (dev unless set; or pass --env prod to a command).
-# HAWK_APPS_ENV=prod
-
-# Publisher key for this project only. Prefer \`npx hawk-app login --local\` so it isn't typed into a file. Never commit it.
-# HAWK_APPS_PUBLISHER_KEY=
-
-# The client (and site) \`hawk-app dev\` runs the app with; it asks the first time and saves the client here.
-# HAWK_APPS_DEV_CLIENT=
-# HAWK_APPS_DEV_ENGINE=
-`;
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { credentialsPath, normalizeUrl, readCredentials } from './credentials.mjs';
+
+export const ENV_FILES = ['.env.local', '.env'];
+
+/** The platform of each environment (`--env` / HAWK_APPS_ENV). */
+export const PLATFORMS = {
+    dev: 'https://api-dev.hawksearchapps.com',
+    prod: 'https://api.hawksearchapps.com',
+};
+
+/** Dev, unless a command, the environment or the project says otherwise: prod is never a default. */
+export const DEFAULT_PLATFORM_URL = PLATFORMS.dev;
+
+/** The URL of an environment name; throws for an unknown one (a typo must not fall back to dev or prod). */
+export function platformForEnv(name, source) {
+    if (!name) return undefined;
+    const url = PLATFORMS[String(name).trim().toLowerCase()];
+    if (!url) throw new Error(`Unknown environment "${name}" (${source}): use ${Object.keys(PLATFORMS).join(' or ')}.`);
+    return url;
+}
+
+/** "prod (https://…)" for a known platform, else the URL. */
+export function describePlatform(url) {
+    const name = Object.entries(PLATFORMS).find(([, u]) => normalizeUrl(u) === normalizeUrl(url))?.[0];
+    return name ? `${name} (${url})` : String(url);
+}
+const PREFIX = 'HAWK_APPS_';
+
+/** Parses KEY=VALUE lines; supports comments, blank lines, `export KEY=...` and single/double quotes. */
+export function parseEnv(text) {
+    const values = {};
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match) continue;
+        let value = match[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        } else {
+            value = value.replace(/\s+#.*$/, '');
+        }
+        values[match[1]] = value;
+    }
+    return values;
+}
+
+/**
+ * Loads HAWK_APPS_* settings from .env.local / .env in `dir`. Variables already set in the environment win,
+ * so CI secrets always take precedence. Only HAWK_APPS_* keys are applied.
+ * @returns {{ loaded: string[], warnings: string[] }}
+ */
+export function loadEnv(dir = process.cwd(), env = process.env, isIgnored = gitIgnored) {
+    const loaded = [];
+    const warnings = [];
+    for (const file of ENV_FILES) {
+        const path = join(dir, file);
+        if (!existsSync(path)) continue;
+        const values = parseEnv(readFileSync(path, 'utf8'));
+        for (const [key, value] of Object.entries(values)) {
+            if (!key.startsWith(PREFIX) || !value || env[key] !== undefined) continue;
+            env[key] = value;
+            loaded.push(`${key} (${file})`);
+        }
+        if (values.HAWK_APPS_PUBLISHER_KEY && isIgnored(dir, file) === false) {
+            warnings.push(`${file} contains your publisher key but is not git-ignored. Add it to .gitignore so the key is never committed.`);
+        }
+    }
+    return { loaded, warnings };
+}
+
+/**
+ * Where the platform URL and publisher key come from, highest priority first:
+ *   URL: --platform / --env, HAWK_APPS_PLATFORM_URL / HAWK_APPS_ENV, project .env.local / .env (the same two), dev.
+ *        `hawk-app login` never changes it: logging in to prod doesn't make later commands use prod.
+ *   Key: HAWK_APPS_PUBLISHER_KEY, project .env.local / .env, the key saved by `hawk-app login` for that URL.
+ */
+// credentialsFile defaults to this machine's `hawk-app login` file, so every command sees the saved login (not just whoami).
+export function resolveSettings({ flagPlatform, flagEnv, env = process.env, dir = process.cwd(), credentialsFile = credentialsPath(env) } = {}) {
+    if (flagPlatform && flagEnv) throw new Error('Use --env or --platform, not both.');
+    const fileValues = {};
+    const fileSource = {};
+    for (const file of [...ENV_FILES].reverse()) {
+        const path = join(dir, file);
+        if (!existsSync(path)) continue;
+        for (const [key, value] of Object.entries(parseEnv(readFileSync(path, 'utf8')))) {
+            if (key.startsWith(PREFIX) && value) {
+                fileValues[key] = value;
+                fileSource[key] = file;
+            }
+        }
+    }
+    const credentials = readCredentials(credentialsFile);
+
+    const [url, urlSource] = first([
+        [flagPlatform, '--platform'],
+        [platformForEnv(flagEnv, '--env'), '--env'],
+        [env.HAWK_APPS_PLATFORM_URL, 'environment'],
+        [platformForEnv(env.HAWK_APPS_ENV, 'HAWK_APPS_ENV'), 'HAWK_APPS_ENV'],
+        [fileValues.HAWK_APPS_PLATFORM_URL, fileSource.HAWK_APPS_PLATFORM_URL],
+        [platformForEnv(fileValues.HAWK_APPS_ENV, fileSource.HAWK_APPS_ENV), fileSource.HAWK_APPS_ENV],
+        [DEFAULT_PLATFORM_URL, 'default (dev)'],
+    ]);
+    const platform = normalizeUrl(url);
+    const [key, keySource] = first([
+        [env.HAWK_APPS_PUBLISHER_KEY, 'environment'],
+        [fileValues.HAWK_APPS_PUBLISHER_KEY, fileSource.HAWK_APPS_PUBLISHER_KEY],
+        [credentials.platforms[platform]?.publisherKey, credentialsFile],
+    ]);
+    return { url: platform, urlSource, key, keySource, credentialsFile };
+}
+
+function first(candidates) {
+    return candidates.find(([value]) => value) ?? [undefined, undefined];
+}
+
+/** true / false inside a git repo; undefined when git isn't available or this isn't a repo. */
+function gitIgnored(dir, file) {
+    const result = spawnSync('git', ['check-ignore', '-q', file], { cwd: dir, stdio: 'ignore' });
+    if (result.error || result.status === 128) return undefined;
+    return result.status === 0;
+}
+
+export const ENV_EXAMPLE = `# Optional per-project overrides. Normally you don't need this file: run \`npx hawk-app sso\` once per machine.
+# To override for this project only, copy to .env.local (git-ignored) and uncomment.
+# Environment variables (e.g. CI secrets) take precedence over both.
+
+# The environment this project deploys to (dev unless set; or pass --env prod to a command).
+# HAWK_APPS_ENV=prod
+
+# Publisher key for this project only. Prefer \`npx hawk-app login --local\` so it isn't typed into a file. Never commit it.
+# HAWK_APPS_PUBLISHER_KEY=
+
+# The client (and site) \`hawk-app dev\` runs the app with; it asks the first time and saves the client here.
+# HAWK_APPS_DEV_CLIENT=
+# HAWK_APPS_DEV_ENGINE=
+`;