@bridgeline-digital/hawk-app-cli 0.0.0-stage → 0.1.0-dev.20261020205204

package/src/env.mjs

@@ -0,0 +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=
+`;

package/src/functions.mjs

@@ -0,0 +1,313 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { zipSync } from 'fflate';
+
+// App functions (`functions:invoke`): functions/<name>.ts (or .js/.mts/.mjs) next to hawk-app.json, declared under
+// "functions" in the manifest, bundled with esbuild into one index.mjs per function and deployed with each version
+// as an AWS Lambda version. Same limits as the platform, which validates again on deploy.
+export const FUNCTIONS_DIR = 'functions';
+export const FUNCTIONS_SCOPE = 'functions:invoke';
+export const BRIDGE_PACKAGE = '@bridgeline-digital/hawk-app-bridge';
+export const MAX_FUNCTIONS = 10;
+export const MAX_NAME_LENGTH = 40;
+export const MAX_SECRETS = 20;
+export const TIMEOUT = { min: 1, max: 25, default: 10 };
+/** Background jobs ("job": true): started with app.functions.start, not called, so they may run longer. */
+export const JOB_TIMEOUT = { min: 1, max: 900, default: 300 };
+export const MEMORY = { min: 128, max: 1024, default: 256 };
+export const MAX_BUNDLE_BYTES = 10 * 1024 * 1024;
+export const MAX_SOURCE_BYTES = 5 * 1024 * 1024;
+export const ENTRY_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs'];
+
+export const FUNCTION_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+const CONFIG_KEYS = ['job', 'timeoutSeconds', 'memoryMb', 'secrets', 'clientSecrets'];
+const MAX_CLIENT_SECRETS = 10;
+/** Fixed zip entry time, so a zip's bytes (and the Lambda codeSha256) only change when the code does. */
+const ZIP_TIME = new Date(1980, 0, 1, 0, 0, 0);
+
+/**
+ * Checks the manifest's "functions" block (names, settings, the functions:invoke scope).
+ * @returns {string[]} errors
+ */
+export function validateFunctionsManifest(manifest) {
+    const errors = [];
+    const functions = manifest?.functions;
+    if (functions === undefined) return errors;
+    if (!functions || typeof functions !== 'object' || Array.isArray(functions)) {
+        errors.push('functions must be an object: { "<name>": { "timeoutSeconds": 10, "memoryMb": 256, "secrets": [] } }.');
+        return errors;
+    }
+    const names = Object.keys(functions);
+    if (names.length > MAX_FUNCTIONS) errors.push(`functions: at most ${MAX_FUNCTIONS} functions per app (found ${names.length}).`);
+    for (const name of names) {
+        const where = `functions.${name}`;
+        if (!FUNCTION_NAME.test(name) || name.length > MAX_NAME_LENGTH) {
+            errors.push(`${where}: function names must be 1-${MAX_NAME_LENGTH} lowercase letters, digits and single dashes (e.g. "sync-feed").`);
+        }
+        const config = functions[name];
+        if (!config || typeof config !== 'object' || Array.isArray(config)) {
+            errors.push(`${where} must be an object, e.g. { "timeoutSeconds": 10, "memoryMb": 256, "secrets": [] } (or {} for the defaults).`);
+            continue;
+        }
+        const unknown = Object.keys(config).filter((key) => !CONFIG_KEYS.includes(key));
+        if (unknown.length) errors.push(`${where}: unknown setting${unknown.length === 1 ? '' : 's'} ${unknown.map((k) => `"${k}"`).join(', ')} (allowed: ${CONFIG_KEYS.join(', ')}).`);
+        if (config.job !== undefined && typeof config.job !== 'boolean') errors.push(`${where}.job must be true or false.`);
+        const timeout = config.job === true ? JOB_TIMEOUT : TIMEOUT;
+        if (config.timeoutSeconds !== undefined && !isIntIn(config.timeoutSeconds, timeout)) {
+            const hint = config.job === true ? '' : `; up to ${JOB_TIMEOUT.max} with "job": true`;
+            errors.push(`${where}.timeoutSeconds must be a whole number from ${timeout.min} to ${timeout.max} (default ${timeout.default}${hint}).`);
+        }
+        if (config.memoryMb !== undefined && !isIntIn(config.memoryMb, MEMORY)) {
+            errors.push(`${where}.memoryMb must be a whole number from ${MEMORY.min} to ${MEMORY.max} (default ${MEMORY.default}).`);
+        }
+        if (config.secrets !== undefined) {
+            const secrets = config.secrets;
+            if (!Array.isArray(secrets)) {
+                errors.push(`${where}.secrets must be a list of names, e.g. ["FEED_API_KEY"].`);
+            } else {
+                const bad = secrets.filter((s) => typeof s !== 'string' || !SECRET_NAME.test(s));
+                if (bad.length) errors.push(`${where}.secrets: ${bad.map((s) => JSON.stringify(s)).join(', ')} must be UPPER_SNAKE_CASE names (a letter, then letters, digits or _; up to 64).`);
+                const duplicates = [...new Set(secrets.filter((s, i) => secrets.indexOf(s) !== i))];
+                if (duplicates.length) errors.push(`${where}.secrets lists ${duplicates.join(', ')} more than once.`);
+                if (secrets.length > MAX_SECRETS) errors.push(`${where}.secrets: at most ${MAX_SECRETS} secrets per function.`);
+            }
+        }
+        if (config.clientSecrets !== undefined) {
+            const names = config.clientSecrets;
+            if (!Array.isArray(names)) {
+                errors.push(`${where}.clientSecrets must be a list of names, e.g. ["MAILCHIMP_API_KEY"].`);
+            } else {
+                const bad = names.filter((s) => typeof s !== 'string' || !SECRET_NAME.test(s));
+                if (bad.length) errors.push(`${where}.clientSecrets: ${bad.map((s) => JSON.stringify(s)).join(', ')} must be UPPER_SNAKE_CASE names (a letter, then letters, digits or _; up to 64).`);
+                const duplicates = [...new Set(names.filter((s, i) => names.indexOf(s) !== i))];
+                if (duplicates.length) errors.push(`${where}.clientSecrets lists ${duplicates.join(', ')} more than once.`);
+                if (names.length > MAX_CLIENT_SECRETS) errors.push(`${where}.clientSecrets: at most ${MAX_CLIENT_SECRETS} client secrets per function.`);
+            }
+        }
+    }
+    if (names.length && !(manifest.scopes ?? []).includes(FUNCTIONS_SCOPE)) {
+        errors.push(`functions need the "${FUNCTIONS_SCOPE}" scope: add it to "scopes" in hawk-app.json.`);
+    }
+    return errors;
+}
+
+const isIntIn = (value, { min, max }) => Number.isInteger(value) && value >= min && value <= max;
+
+/** A function's settings with the defaults filled in, as sent to the platform. */
+export function functionConfig(config = {}) {
+    const job = config.job === true;
+    return {
+        job,
+        timeoutSeconds: config.timeoutSeconds ?? (job ? JOB_TIMEOUT : TIMEOUT).default,
+        memoryMb: config.memoryMb ?? MEMORY.default,
+        secrets: config.secrets ?? [],
+        clientSecrets: config.clientSecrets ?? [],
+    };
+}
+
+/**
+ * Matches the manifest's functions with the entry files in `<projectDir>/functions`. Null when the app has neither.
+ * Every declared function needs functions/<name>.(ts|mts|js|mjs), and every entry file there needs a manifest entry
+ * (shared code goes in subfolders such as functions/lib/).
+ * @returns {Promise<{ functions: { name: string, entry: string, config: object }[], errors: string[] } | null>}
+ */
+export async function loadFunctions(projectDir, manifest) {
+    const declared = manifest?.functions && typeof manifest.functions === 'object' && !Array.isArray(manifest.functions) ? manifest.functions : {};
+    const dir = join(projectDir, FUNCTIONS_DIR);
+    const hasDir = existsSync(dir);
+    if (!hasDir && !Object.keys(declared).length) return null;
+
+    const errors = [];
+    const entries = new Map();
+    if (hasDir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (!entry.isFile() || entry.name.startsWith('.') || entry.name.endsWith('.d.ts')) continue;
+            const ext = ENTRY_EXTENSIONS.find((e) => entry.name.endsWith(e));
+            if (!ext) continue;
+            const name = entry.name.slice(0, -ext.length);
+            if (entries.has(name)) {
+                errors.push(`${FUNCTIONS_DIR}/: ${name} has more than one entry file (${entries.get(name).file} and ${entry.name}); keep one.`);
+                continue;
+            }
+            entries.set(name, { file: entry.name, full: join(dir, entry.name) });
+        }
+    }
+
+    const functions = [];
+    for (const name of Object.keys(declared).sort()) {
+        const entry = entries.get(name);
+        if (!entry) {
+            errors.push(`functions.${name} has no entry file: add ${FUNCTIONS_DIR}/${name}.ts (or .js/.mts/.mjs) exporting \`handler\`.`);
+            continue;
+        }
+        functions.push({ name, entry: entry.full, config: functionConfig(declared[name]) });
+    }
+    for (const [name, entry] of entries) {
+        if (!(name in declared)) {
+            errors.push(`${FUNCTIONS_DIR}/${entry.file} is not declared in hawk-app.json: add "${name}": {} under "functions", or move shared code into a subfolder (e.g. ${FUNCTIONS_DIR}/lib/).`);
+        }
+    }
+    if (hasDir && !entries.size && !Object.keys(declared).length) {
+        errors.push(`${FUNCTIONS_DIR}/ has no functions: add ${FUNCTIONS_DIR}/<name>.ts and declare it under "functions" in hawk-app.json, or remove the folder.`);
+    }
+    return { functions, errors };
+}
+
+/**
+ * Checks that the app has a bridge with the `/server` entry (the wrapper imports `toLambdaHandler` from it).
+ * @returns {string | null} an error message, or null when it's fine
+ */
+export function checkBridge(projectDir) {
+    let packageFile;
+    try {
+        packageFile = createRequire(join(projectDir, 'package.json')).resolve(`${BRIDGE_PACKAGE}/package.json`);
+    } catch {
+        return `Functions need ${BRIDGE_PACKAGE} in the app: run \`npm install ${BRIDGE_PACKAGE}\`.`;
+    }
+    const pkg = JSON.parse(readFileSync(packageFile, 'utf8'));
+    if (!pkg.exports?.['./server']) {
+        return `${BRIDGE_PACKAGE} ${pkg.version} has no "/server" entry: update it (\`npm install ${BRIDGE_PACKAGE}@latest\`).`;
+    }
+    return null;
+}
+
+/** The generated entry: the user's module wrapped as the Lambda handler. */
+export function wrapperSource(entry) {
+    const userModule = entry.split(sep).join('/');
+    return [
+        `import { toLambdaHandler } from '${BRIDGE_PACKAGE}/server';`,
+        `import { handler as userHandler } from ${JSON.stringify(userModule)};`,
+        'export const handler = toLambdaHandler(userHandler);',
+        '',
+    ].join('\n');
+}
+
+/**
+ * Bundles one function (esbuild: node22, ESM, every dependency included) and packs what the platform needs:
+ * `bundle.zip` (index.mjs exporting `handler`), `source.zip` (every file under functions/, for review) and
+ * `deps.json` ([{ name, version }] of the packages in the bundle).
+ * @returns {Promise<{ name: string, files: { path: string, size: number, data: Uint8Array }[], bundleBytes: number, deps: { name: string, version: string }[] }>}
+ */
+export async function buildFunction({ projectDir, name, entry, sourceZip }) {
+    const problem = checkBridge(projectDir);
+    if (problem) throw new Error(problem);
+    const esbuild = await import('esbuild');
+    let result;
+    try {
+        result = await esbuild.build({
+            stdin: { contents: wrapperSource(entry), resolveDir: projectDir, sourcefile: `hawk-function-${name}.mjs`, loader: 'js' },
+            absWorkingDir: projectDir,
+            bundle: true,
+            platform: 'node',
+            target: 'node22',
+            format: 'esm',
+            outfile: 'index.mjs',
+            write: false,
+            metafile: true,
+            logLevel: 'silent',
+            legalComments: 'none',
+            // CommonJS dependencies that call require() need it in an ES module.
+            banner: { js: "import { createRequire as __hawkCreateRequire } from 'node:module';\nconst require = __hawkCreateRequire(import.meta.url);" },
+        });
+    } catch (error) {
+        const messages = (error.errors ?? []).map((e) => `  ${e.location ? `${e.location.file}:${e.location.line}: ` : ''}${e.text}`);
+        const missingHandler = (error.errors ?? []).some((e) => /No matching export .* for import "handler"/.test(e.text));
+        throw new Error(
+            `Could not bundle function "${name}"${missingHandler ? ` (${FUNCTIONS_DIR}/${name} must export \`handler\`)` : ''}:\n${messages.join('\n') || `  ${error.message}`}`,
+        );
+    }
+    const code = result.outputFiles.find((f) => f.path.endsWith('index.mjs')).contents;
+    const bundle = zip({ 'index.mjs': code });
+    if (bundle.length > MAX_BUNDLE_BYTES) {
+        throw new Error(`Function "${name}" is ${formatMb(bundle.length)} zipped; the limit is ${formatMb(MAX_BUNDLE_BYTES)}. Drop large dependencies.`);
+    }
+    const deps = dependencies(result.metafile, projectDir);
+    const depsJson = new TextEncoder().encode(JSON.stringify(deps, null, 2) + '\n');
+    const source = sourceZip ?? (await zipSources(projectDir));
+    const prefix = `${FUNCTIONS_DIR}/${name}`;
+    return {
+        name,
+        bundleBytes: bundle.length,
+        deps,
+        files: [
+            { path: `${prefix}/bundle.zip`, size: bundle.length, data: bundle },
+            { path: `${prefix}/source.zip`, size: source.length, data: source },
+            { path: `${prefix}/deps.json`, size: depsJson.length, data: depsJson },
+        ],
+    };
+}
+
+/** Zips every file under functions/ (no node_modules or hidden files), with paths like functions/lib/feed.ts. */
+export async function zipSources(projectDir) {
+    const root = join(projectDir, FUNCTIONS_DIR);
+    const files = {};
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else if (entry.isFile()) files[relative(projectDir, full).split(sep).join('/')] = new Uint8Array(await readFile(full));
+        }
+    }
+    if (existsSync(root)) await walk(root);
+    const zipped = zip(files);
+    if (zipped.length > MAX_SOURCE_BYTES) {
+        throw new Error(`${FUNCTIONS_DIR}/ is ${formatMb(zipped.length)} zipped; the limit is ${formatMb(MAX_SOURCE_BYTES)}. Keep data files and builds out of it.`);
+    }
+    return zipped;
+}
+
+/** A zip with sorted entries and fixed timestamps: the same files always give the same bytes. */
+export function zip(files) {
+    const sorted = {};
+    for (const path of Object.keys(files).sort()) sorted[path] = [files[path], { mtime: ZIP_TIME }];
+    return zipSync(sorted, { level: 9, mtime: ZIP_TIME });
+}
+
+/** The packages in the bundle, from the esbuild metafile: every input outside the app's own code, by its package.json. */
+export function dependencies(metafile, projectDir) {
+    const found = new Map();
+    const appModules = join(projectDir, 'node_modules');
+    for (const input of Object.keys(metafile.inputs)) {
+        // <stdin> is the generated wrapper; "ns:…" inputs come from other esbuild namespaces, not files.
+        if (input.startsWith('<') || /^[a-z-]{2,}:/i.test(input)) continue;
+        const full = resolve(projectDir, input);
+        const inApp = !relative(projectDir, full).startsWith('..') && !full.startsWith(appModules + sep);
+        if (inApp) continue;
+        const pkg = nearestPackage(dirname(full));
+        if (pkg?.name && !found.has(pkg.name)) found.set(pkg.name, pkg.version ?? 'unknown');
+    }
+    return [...found].sort(([a], [b]) => a.localeCompare(b)).map(([name, version]) => ({ name, version }));
+}
+
+function nearestPackage(dir) {
+    for (let current = dir; ; current = dirname(current)) {
+        const file = join(current, 'package.json');
+        if (existsSync(file)) {
+            try {
+                const pkg = JSON.parse(readFileSync(file, 'utf8'));
+                // Nested package.json files that only set "type" (e.g. dist/esm/package.json) aren't the package.
+                if (pkg.name) return pkg;
+            } catch {
+                // Unreadable: keep looking up.
+            }
+        }
+        if (dirname(current) === current) return null;
+    }
+}
+
+export function describeFunctions(count) {
+    return `${count} function${count === 1 ? '' : 's'}`;
+}
+
+/** "20 s, 512 MB, secrets FEED_API_KEY" ("job, 300 s, …" for a background job) */
+export function describeConfig(config) {
+    return `${config.job ? 'job, ' : ''}${config.timeoutSeconds} s, ${config.memoryMb} MB${config.secrets.length ? `, secrets ${config.secrets.join(' ')}` : ''}${config.clientSecrets?.length ? `, client secrets ${config.clientSecrets.join(' ')}` : ''}`;
+}
+
+function formatMb(bytes) {
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/src/login.mjs

@@ -0,0 +1,166 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { appendFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { credentialsPath, removeCredential, saveCredential } from './credentials.mjs';
+import { describePlatform, resolveSettings } from './env.mjs';
+
+/** Reads a line from the terminal without echoing it. */
+export function promptHidden(
+    question,
+    {
+        input = process.stdin,
+        output = process.stdout,
+        notInteractive = '`hawk-app login` needs an interactive terminal. In CI, set HAWK_APPS_PUBLISHER_KEY as a secured variable instead.',
+    } = {},
+) {
+    if (!input.isTTY) {
+        return Promise.reject(new Error(notInteractive));
+    }
+    return new Promise((resolve, reject) => {
+        let value = '';
+        output.write(question);
+        input.setRawMode(true);
+        input.resume();
+        input.setEncoding('utf8');
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === '\r' || ch === '\n') {
+                    finish();
+                    return resolve(value.trim());
+                }
+                if (ch === '\u0003') {
+                    finish();
+                    return reject(new Error('Cancelled.'));
+                }
+                if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1);
+                else if (ch >= ' ') value += ch;
+            }
+        };
+        function finish() {
+            input.off('data', onData);
+            input.setRawMode(false);
+            input.pause();
+            output.write('\n');
+        }
+        input.on('data', onData);
+    });
+}
+
+/** Sets or replaces KEY=value lines in a .env file, keeping everything else (comments, other keys) as is. */
+export function upsertEnv(text, values) {
+    const lines = text ? text.split(/\r?\n/) : [];
+    const pending = { ...values };
+    const updated = lines.map((line) => {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
+        if (match && match[1] in pending) {
+            const next = `${match[1]}=${pending[match[1]]}`;
+            delete pending[match[1]];
+            return next;
+        }
+        return line;
+    });
+    while (updated.length && updated[updated.length - 1] === '') updated.pop();
+    for (const [key, value] of Object.entries(pending)) updated.push(`${key}=${value}`);
+    return updated.join('\n') + '\n';
+}
+
+/** Checks a key with the platform: 404 = accepted (no app by that name), 401 = rejected. */
+export async function checkKey(url, key, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(`${url}/publish/apps/login-check`, { headers: { Authorization: `PublisherKey ${key}` } });
+    } catch (error) {
+        return { ok: false, reason: `Could not reach ${url}: ${error.message}.` };
+    }
+    if (response.status === 401) return { ok: false, reason: 'The platform rejected the key.' };
+    if (response.status !== 404 && !response.ok) return { ok: false, reason: `Unexpected response from the platform (${response.status}).` };
+    return { ok: true };
+}
+
+const publisherOf = (key) => key.split('.')[0];
+
+/**
+ * Asks for the publisher key, checks it with the platform and saves it once for this machine, so every app
+ * uses it. With `local: true` it goes into this project's .env.local instead. The key never appears on
+ * screen, in shell history or as a command-line argument.
+ */
+export async function login({
+    dir = process.cwd(),
+    platform,
+    env,
+    local = false,
+    prompt = promptHidden,
+    fetchImpl = fetch,
+    log = console.log,
+    isIgnored = gitIgnored,
+    credentialsFile = credentialsPath(),
+}) {
+    const { url } = resolveSettings({ flagPlatform: platform, flagEnv: env, dir, credentialsFile });
+
+    log(`Platform: ${describePlatform(url)}`);
+    const key = await prompt('Publisher key (input hidden): ');
+    if (!/^[a-z0-9-]+\.[A-Za-z0-9_-]{16,}$/.test(key)) throw new Error('That does not look like a publisher key ("<publisherId>.<secret>"). Nothing was saved.');
+    const check = await checkKey(url, key, fetchImpl);
+    if (!check.ok) throw new Error(`${check.reason} Nothing was saved.`);
+
+    if (!local) {
+        await saveCredential(credentialsFile, url, key);
+        log(`✔ Logged in to ${describePlatform(url)} as publisher "${publisherOf(key)}".`);
+        log(`  Saved for every app on this machine: ${credentialsFile}`);
+        return;
+    }
+
+    const envPath = join(dir, '.env.local');
+    const existing = existsSync(envPath) ? readFileSync(envPath, 'utf8') : '';
+    await writeFile(envPath, upsertEnv(existing, { HAWK_APPS_PLATFORM_URL: url, HAWK_APPS_PUBLISHER_KEY: key }));
+    log(`✔ Logged in to ${url} as publisher "${publisherOf(key)}" for this project only (.env.local).`);
+    if (isIgnored(dir, '.env.local') === false || (isIgnored(dir, '.env.local') === undefined && !ignoredByGitignoreFile(dir))) {
+        const gitignore = join(dir, '.gitignore');
+        const needsNewline = existsSync(gitignore) && !readFileSync(gitignore, 'utf8').endsWith('\n');
+        await appendFile(gitignore, `${needsNewline ? '\n' : ''}.env.local\n`);
+        log('  Added .env.local to .gitignore so the key is never committed.');
+    }
+}
+
+/** Shows which platform and key would be used here, and whether the platform accepts the key. */
+export async function whoami({ dir = process.cwd(), platform, env, fetchImpl = fetch, log = console.log, credentialsFile = credentialsPath() }) {
+    const settings = resolveSettings({ flagPlatform: platform, flagEnv: env, dir, credentialsFile });
+    log(`Platform: ${describePlatform(settings.url)}  (from ${settings.urlSource})`);
+    if (!settings.key) {
+        log('✖ Not logged in. Run `npx hawk-app sso` (Bridgeline account) or `npx hawk-app login` (publisher key) once on this machine.');
+        return 1;
+    }
+    const check = await checkKey(settings.url, settings.key, fetchImpl);
+    if (!check.ok) {
+        log(`✖ ${check.reason} Key from ${settings.keySource}. Run \`npx hawk-app sso\` or \`npx hawk-app login\` again.`);
+        return 1;
+    }
+    log(`✔ Logged in as publisher "${publisherOf(settings.key)}"  (key from ${settings.keySource})`);
+    return 0;
+}
+
+/** Removes this machine's saved key for the platform. Keys in .env.local or the environment are not touched. */
+export async function logout({ dir = process.cwd(), platform, env, log = console.log, credentialsFile = credentialsPath() }) {
+    const { url } = resolveSettings({ flagPlatform: platform, flagEnv: env, dir, credentialsFile });
+    if (await removeCredential(credentialsFile, url)) log(`✔ Logged out of ${url} on this machine.`);
+    else log(`Not logged in to ${url} on this machine.`);
+    const remaining = resolveSettings({ flagPlatform: platform, flagEnv: env, dir, credentialsFile });
+    if (remaining.key) log(`  Note: a key is still set in ${remaining.keySource}; that one still applies here.`);
+    return 0;
+}
+
+function ignoredByGitignoreFile(dir) {
+    const path = join(dir, '.gitignore');
+    if (!existsSync(path)) return false;
+    return readFileSync(path, 'utf8')
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .some((l) => l === '.env.local' || l === '.env*' || l === '.env.*' || l === '*.local');
+}
+
+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;
+}