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

package/src/create.mjs

@@ -1,186 +1,186 @@
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { planAgentFiles, writeAgentFiles } from './agents.mjs';
-import { credentialsPath } from './credentials.mjs';
-import { ENV_EXAMPLE, resolveSettings } from './env.mjs';
-import { newManifest } from './manifest.mjs';
-import { DEFAULT_ICON_SVG } from './app-icon.mjs';
-import { applyChannel, CHANNELS, cliChannel, DEV_CHANNEL_NOTE, planChannel, writeCdnFiles } from './channel.mjs';
-
-const TEMPLATES_DIR = fileURLToPath(new URL('../templates', import.meta.url));
-
-export const TEMPLATES = {
-    react: { description: 'React + Vite + TypeScript + the UI kit (Spark\'s stylesheet and elements)', build: 'dist', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
-    preact: { description: 'Preact + Vite + TypeScript (small bundle) + the UI kit (stylesheet and elements)', build: 'dist', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
-    next: { description: 'Next.js (static export) + TypeScript + the UI kit (stylesheet and elements)', build: 'out', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
-    'next-mui': {
-        description: 'Next.js (static export) + Material UI 9 + the UI kit (Spark\'s theme and components)',
-        build: 'out',
-        dev: 'npm run dev',
-        devUrl: (slug) => `http://localhost:3100/${slug}/`,
-    },
-    vanilla: { description: 'Plain HTML + JavaScript, no build step (the bridge and the UI kit from the CDN)', build: 'public', dev: 'npm run dev', devUrl: () => 'http://localhost:3100/' },
-};
-
-export function toSlug(value) {
-    return (
-        String(value)
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, '-')
-            .replace(/^-+|-+$/g, '')
-            .slice(0, 64) || 'my-app'
-    );
-}
-
-export function titleCase(slug) {
-    return slug
-        .split('-')
-        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
-        .join(' ');
-}
-
-/** Scaffolds a new Hawk App project from one of the built-in templates. */
-/** @param checkSlug Refuses a taken slug before anything is written (create's own check: see slug-guard.mjs). */
-/**
- * @param channel `latest` or `dev`: which builds of the bridge and CLI the app follows. Default: this CLI's own channel,
- * so `npx …-cli@dev create` makes a dev app (see channel.mjs).
- */
-export async function createProject({ target, template = 'react', name, install = false, checkSlug, channel = cliChannel(), log = console.log, credentialsFile = credentialsPath() }) {
-    if (!CHANNELS.includes(channel)) throw new Error(`--channel must be latest or dev, not "${channel}".`);
-    if (!target) throw new Error(`Usage: hawk-app create <folder> [--template ${Object.keys(TEMPLATES).join('|')}] [--name "Display Name"] [--install]`);
-    const spec = TEMPLATES[template];
-    if (!spec) throw new Error(`Unknown template "${template}". Choose one of: ${Object.keys(TEMPLATES).join(', ')}.`);
-
-    const dir = resolve(target);
-    if (existsSync(dir) && (await readdir(dir)).length > 0) throw new Error(`"${target}" already exists and is not empty.`);
-    const slug = toSlug(basename(dir));
-    if (checkSlug) await checkSlug(slug);
-    const displayName = name ?? titleCase(slug);
-    const cliVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-    const replacements = { __SLUG__: slug, __NAME__: displayName, __CLI_VERSION__: cliVersion };
-
-    const source = join(TEMPLATES_DIR, template);
-    const written = [];
-    for (const file of await listTemplateFiles(source)) {
-        const content = (await readFile(join(source, file), 'utf8')).replace(/__SLUG__|__NAME__|__CLI_VERSION__/g, (m) => replacements[m]);
-        await writeOut(join(dir, file), content);
-        written.push(file);
-    }
-
-    // A dev app: the Hawk packages (and the vanilla CDN import) on the dev tag, not the release the template pins.
-    if (channel === 'dev') {
-        const pkgFile = join(dir, 'package.json');
-        const appJsFile = join(dir, 'public', 'app.js');
-        const pkg = existsSync(pkgFile) ? JSON.parse(await readFile(pkgFile, 'utf8')) : null;
-        const appJs = existsSync(appJsFile) ? await readFile(appJsFile, 'utf8') : null;
-        const plan = planChannel({ pkg, appJs, channel, latestVersion: () => null });
-        applyChannel(plan, pkg ?? {}, appJs);
-        if (pkg && plan.dependencies.length) await writeOut(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
-        // The bridge and the kit from the CDN (app.js, index.html).
-        if (plan.cdn) await writeCdnFiles(dir, plan.cdn.to);
-    }
-
-    await writeOut(join(dir, 'hawk-app.json'), JSON.stringify(newManifest({ slug, name: displayName, template }), null, 2) + '\n');
-    await writeOut(join(dir, 'icon.svg'), DEFAULT_ICON_SVG);
-    await writeOut(join(dir, '.gitignore'), ['node_modules/', 'dist/', 'out/', '.next/', 'next-env.d.ts', '.env', '.env.local', '.env.*.local', '*.log', ''].join('\n'));
-    await writeOut(join(dir, '.env.example'), ENV_EXAMPLE);
-    await writeOut(join(dir, 'README.md'), readme({ slug, displayName, template, spec }));
-    const agentFiles = await writeAgentFiles(dir, planAgentFiles(dir, { slug, name: displayName, template }));
-
-    log(`✔ Created ${displayName} (${spec.description}) in ${relative(process.cwd(), dir) || '.'}`);
-    log(`  slug: ${slug} → each deploy is served at <apps CDN>/${slug}/v<n>/`);
-    log('  AGENTS.md tells AI coding assistants (Claude Code, Copilot, Cursor, …) how Hawk Apps work.');
-    if (channel === 'dev') DEV_CHANNEL_NOTE.forEach((line) => log(`  ${line}`));
-
-    if (install) {
-        log('  Installing dependencies…');
-        const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'inherit', shell: process.platform === 'win32' });
-        if (result.status !== 0) throw new Error('npm install failed. Run it yourself in the new folder.');
-    }
-
-    log('\nNext steps:');
-    log(`  cd ${relative(process.cwd(), dir) || '.'}`);
-    if (!install) log('  npm install');
-    const { key, url } = resolveSettings({ dir, credentialsFile });
-    if (!key) log('  npx hawk-app sso                          (once per machine: sign in with your Bridgeline account)');
-    log("  npm run app:dev                           (run it locally inside a stand-in for HawkSearch, with a client's data)");
-    log(`  npm run app:deploy                        (${template === 'vanilla' ? 'uploads public/' : 'builds and uploads'} a new version, with hawk-app.json)`);
-    log(key ? `\n  Logged in to ${url}. Check everything any time with \`npx hawk-app doctor\`.` : '');
-    log('  It isn\'t released yet: only Bridgeline staff see it, from the Apps page in HawkSearch (`npx hawk-app open`). Submit it');
-    log('  for approval there; an approver releases it. `npx hawk-app --help` lists everything else.');
-    log('  Docs: https://developers.hawksearchapps.com (npx hawk-app docs), with your Bridgeline account.');
-    return { dir, slug, files: [...written, 'hawk-app.json', 'icon.svg', '.gitignore', '.env.example', 'README.md', ...agentFiles] };
-}
-
-async function listTemplateFiles(root) {
-    const files = [];
-    async function walk(current) {
-        for (const entry of await readdir(current, { withFileTypes: true })) {
-            const full = join(current, entry.name);
-            if (entry.isDirectory()) await walk(full);
-            else files.push(relative(root, full));
-        }
-    }
-    await walk(root);
-    return files.sort();
-}
-
-async function writeOut(path, content) {
-    await mkdir(resolve(path, '..'), { recursive: true });
-    await writeFile(path, content);
-}
-
-function readme({ slug, displayName, template, spec }) {
-    return `# ${displayName}
-
-A Hawk App: a tool that runs inside HawkSearch (today's dashboard, Spark later) and gets its context and data through
-[\`@bridgeline-digital/hawk-app-bridge\`](https://www.npmjs.com/package/@bridgeline-digital/hawk-app-bridge).
-Created with \`hawk-app create --template ${template}\` (${spec.description}).
-
-## Develop
-\`\`\`bash
-npm install
-npx hawk-app sso                           # once per machine: sign in with your Bridgeline account
-npm run app:dev                            # the app inside a local stand-in for HawkSearch, with a client's data
-\`\`\`
-\`app:dev\` runs \`${spec.dev}\` and a stand-in for HawkSearch at http://localhost:3200 with real tokens and data. The
-first time it asks which client (remembered in \`.env.local\`; \`-- --client <id>\` picks another) and registers the
-app (not released). Opened directly in a browser, the app says "Open this app from the Apps page in HawkSearch": it
-needs a host for its context and data. Queries and functions run from the deployed version: deploy after changing them.
-
-To try a local copy inside the real HawkSearch instead, open
-\`<HawkSearch>/admin/apps/${slug}?devUrl=${spec.devUrl(slug)}\` (Bridgeline users, \`http://localhost\` ports 3100-3103).
-
-## Data
-Use the bridge. There are **no API keys in the app**; the platform adds credentials server-side for the current client.
-- \`app.analytics.report('searches' | 'queries' | 'poor-results' | …, { limit })\` needs the \`reports:read\` scope.
-- \`app.dashboard.get('Synonym')\` (HawkSearch dashboard API, read) needs the \`hawksearch:read\` scope.
-- \`app.dashboard.post/put/delete('Synonym', body)\` (writes: synonyms, redirects, banners, landing pages, …) need the \`hawksearch:write\` scope; writes are never retried.
-- \`app.context\` and \`app.onContextChange\` give the client, engine, date range, locale and theme.
-- Own backend? Send \`await app.getToken()\` as \`Authorization: Bearer ...\` and verify it there against the
-  platform's \`/.well-known/jwks.json\`. Don't use cookies: browsers block them inside the host's iframe.
-
-## Ship
-\`\`\`bash
-npm run app:deploy            # ${template === 'vanilla' ? 'upload public/' : `build and upload ${spec.build}/`} as a new version, with hawk-app.json
-npx hawk-app status           # released or not, the newest version, the approval request
-npx hawk-app open             # the app in HawkSearch, to review it and submit it for approval
-npx hawk-app clients add <id> # give a client the app (or manage clients in the Hawk Analytics portal)
-\`\`\`
-Every deploy is a new, numbered version${template === 'vanilla' ? '' : `: \`app:deploy\` builds the app with its base path set to \`/${slug}/v<n>\``},
-with the settings in \`hawk-app.json\` (scopes, origins, views, functions…).
-
-- **Not released at first.** A new app's versions are drafts: only Bridgeline staff see them. Submit a version for
-  approval in HawkSearch; once an approver releases it, the app's clients get it.
-- **Each version is reviewed.** Clients keep the released version until a new one is approved. \`npx hawk-app versions\`
-  lists every version with its status; \`npx hawk-app why <client>\` explains what a client sees.
-- **Test before release.** \`npm run app:deploy -- --alias staging\` deploys a version for an alias (e.g. new clients or a
-  branch) without touching the main line. See versions-and-aliases in the Hawk Apps docs.
-- **Clients any time.** \`npx hawk-app clients add|exclude|remove <id>\` (or the Hawk Analytics portal) applies at once,
-  without a deploy or approval, and is recorded in the app's history.
-- **Something off?** \`npx hawk-app doctor\` checks your login, the platform, the project and the bridge.
-`;
-}
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { planAgentFiles, writeAgentFiles } from './agents.mjs';
+import { credentialsPath } from './credentials.mjs';
+import { ENV_EXAMPLE, resolveSettings } from './env.mjs';
+import { newManifest } from './manifest.mjs';
+import { DEFAULT_ICON_SVG } from './app-icon.mjs';
+import { applyChannel, CHANNELS, cliChannel, DEV_CHANNEL_NOTE, planChannel, writeCdnFiles } from './channel.mjs';
+
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates', import.meta.url));
+
+export const TEMPLATES = {
+    react: { description: 'React + Vite + TypeScript + the UI kit (Spark\'s stylesheet and elements)', build: 'dist', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
+    preact: { description: 'Preact + Vite + TypeScript (small bundle) + the UI kit (stylesheet and elements)', build: 'dist', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
+    next: { description: 'Next.js (static export) + TypeScript + the UI kit (stylesheet and elements)', build: 'out', dev: 'npm run dev', devUrl: (slug) => `http://localhost:3100/${slug}/` },
+    'next-mui': {
+        description: 'Next.js (static export) + Material UI 9 + the UI kit (Spark\'s theme and components)',
+        build: 'out',
+        dev: 'npm run dev',
+        devUrl: (slug) => `http://localhost:3100/${slug}/`,
+    },
+    vanilla: { description: 'Plain HTML + JavaScript, no build step (the bridge and the UI kit from the CDN)', build: 'public', dev: 'npm run dev', devUrl: () => 'http://localhost:3100/' },
+};
+
+export function toSlug(value) {
+    return (
+        String(value)
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .slice(0, 64) || 'my-app'
+    );
+}
+
+export function titleCase(slug) {
+    return slug
+        .split('-')
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+
+/** Scaffolds a new Hawk App project from one of the built-in templates. */
+/** @param checkSlug Refuses a taken slug before anything is written (create's own check: see slug-guard.mjs). */
+/**
+ * @param channel `latest` or `dev`: which builds of the bridge and CLI the app follows. Default: this CLI's own channel,
+ * so `npx …-cli@dev create` makes a dev app (see channel.mjs).
+ */
+export async function createProject({ target, template = 'react', name, install = false, checkSlug, channel = cliChannel(), log = console.log, credentialsFile = credentialsPath() }) {
+    if (!CHANNELS.includes(channel)) throw new Error(`--channel must be latest or dev, not "${channel}".`);
+    if (!target) throw new Error(`Usage: hawk-app create <folder> [--template ${Object.keys(TEMPLATES).join('|')}] [--name "Display Name"] [--install]`);
+    const spec = TEMPLATES[template];
+    if (!spec) throw new Error(`Unknown template "${template}". Choose one of: ${Object.keys(TEMPLATES).join(', ')}.`);
+
+    const dir = resolve(target);
+    if (existsSync(dir) && (await readdir(dir)).length > 0) throw new Error(`"${target}" already exists and is not empty.`);
+    const slug = toSlug(basename(dir));
+    if (checkSlug) await checkSlug(slug);
+    const displayName = name ?? titleCase(slug);
+    const cliVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+    const replacements = { __SLUG__: slug, __NAME__: displayName, __CLI_VERSION__: cliVersion };
+
+    const source = join(TEMPLATES_DIR, template);
+    const written = [];
+    for (const file of await listTemplateFiles(source)) {
+        const content = (await readFile(join(source, file), 'utf8')).replace(/__SLUG__|__NAME__|__CLI_VERSION__/g, (m) => replacements[m]);
+        await writeOut(join(dir, file), content);
+        written.push(file);
+    }
+
+    // A dev app: the Hawk packages (and the vanilla CDN import) on the dev tag, not the release the template pins.
+    if (channel === 'dev') {
+        const pkgFile = join(dir, 'package.json');
+        const appJsFile = join(dir, 'public', 'app.js');
+        const pkg = existsSync(pkgFile) ? JSON.parse(await readFile(pkgFile, 'utf8')) : null;
+        const appJs = existsSync(appJsFile) ? await readFile(appJsFile, 'utf8') : null;
+        const plan = planChannel({ pkg, appJs, channel, latestVersion: () => null });
+        applyChannel(plan, pkg ?? {}, appJs);
+        if (pkg && plan.dependencies.length) await writeOut(pkgFile, JSON.stringify(pkg, null, 2) + '\n');
+        // The bridge and the kit from the CDN (app.js, index.html).
+        if (plan.cdn) await writeCdnFiles(dir, plan.cdn.to);
+    }
+
+    await writeOut(join(dir, 'hawk-app.json'), JSON.stringify(newManifest({ slug, name: displayName, template }), null, 2) + '\n');
+    await writeOut(join(dir, 'icon.svg'), DEFAULT_ICON_SVG);
+    await writeOut(join(dir, '.gitignore'), ['node_modules/', 'dist/', 'out/', '.next/', 'next-env.d.ts', '.env', '.env.local', '.env.*.local', '*.log', ''].join('\n'));
+    await writeOut(join(dir, '.env.example'), ENV_EXAMPLE);
+    await writeOut(join(dir, 'README.md'), readme({ slug, displayName, template, spec }));
+    const agentFiles = await writeAgentFiles(dir, planAgentFiles(dir, { slug, name: displayName, template }));
+
+    log(`✔ Created ${displayName} (${spec.description}) in ${relative(process.cwd(), dir) || '.'}`);
+    log(`  slug: ${slug} → each deploy is served at <apps CDN>/${slug}/v<n>/`);
+    log('  AGENTS.md tells AI coding assistants (Claude Code, Copilot, Cursor, …) how Hawk Apps work.');
+    if (channel === 'dev') DEV_CHANNEL_NOTE.forEach((line) => log(`  ${line}`));
+
+    if (install) {
+        log('  Installing dependencies…');
+        const result = spawnSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'inherit', shell: process.platform === 'win32' });
+        if (result.status !== 0) throw new Error('npm install failed. Run it yourself in the new folder.');
+    }
+
+    log('\nNext steps:');
+    log(`  cd ${relative(process.cwd(), dir) || '.'}`);
+    if (!install) log('  npm install');
+    const { key, url } = resolveSettings({ dir, credentialsFile });
+    if (!key) log('  npx hawk-app sso                          (once per machine: sign in with your Bridgeline account)');
+    log("  npm run app:dev                           (run it locally inside a stand-in for HawkSearch, with a client's data)");
+    log(`  npm run app:deploy                        (${template === 'vanilla' ? 'uploads public/' : 'builds and uploads'} a new version, with hawk-app.json)`);
+    log(key ? `\n  Logged in to ${url}. Check everything any time with \`npx hawk-app doctor\`.` : '');
+    log('  It isn\'t released yet: only Bridgeline staff see it, from the Apps page in HawkSearch (`npx hawk-app open`). Submit it');
+    log('  for approval there; an approver releases it. `npx hawk-app --help` lists everything else.');
+    log('  Docs: https://developers.hawksearchapps.com (npx hawk-app docs), with your Bridgeline account.');
+    return { dir, slug, files: [...written, 'hawk-app.json', 'icon.svg', '.gitignore', '.env.example', 'README.md', ...agentFiles] };
+}
+
+async function listTemplateFiles(root) {
+    const files = [];
+    async function walk(current) {
+        for (const entry of await readdir(current, { withFileTypes: true })) {
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) await walk(full);
+            else files.push(relative(root, full));
+        }
+    }
+    await walk(root);
+    return files.sort();
+}
+
+async function writeOut(path, content) {
+    await mkdir(resolve(path, '..'), { recursive: true });
+    await writeFile(path, content);
+}
+
+function readme({ slug, displayName, template, spec }) {
+    return `# ${displayName}
+
+A Hawk App: a tool that runs inside HawkSearch (today's dashboard, Spark later) and gets its context and data through
+[\`@bridgeline-digital/hawk-app-bridge\`](https://www.npmjs.com/package/@bridgeline-digital/hawk-app-bridge).
+Created with \`hawk-app create --template ${template}\` (${spec.description}).
+
+## Develop
+\`\`\`bash
+npm install
+npx hawk-app sso                           # once per machine: sign in with your Bridgeline account
+npm run app:dev                            # the app inside a local stand-in for HawkSearch, with a client's data
+\`\`\`
+\`app:dev\` runs \`${spec.dev}\` and a stand-in for HawkSearch at http://localhost:3200 with real tokens and data. The
+first time it asks which client (remembered in \`.env.local\`; \`-- --client <id>\` picks another) and registers the
+app (not released). Opened directly in a browser, the app says "Open this app from the Apps page in HawkSearch": it
+needs a host for its context and data. Queries and functions run from the deployed version: deploy after changing them.
+
+To try a local copy inside the real HawkSearch instead, open
+\`<HawkSearch>/admin/apps/${slug}?devUrl=${spec.devUrl(slug)}\` (Bridgeline users, \`http://localhost\` ports 3100-3103).
+
+## Data
+Use the bridge. There are **no API keys in the app**; the platform adds credentials server-side for the current client.
+- \`app.analytics.report('searches' | 'queries' | 'poor-results' | …, { limit })\` needs the \`reports:read\` scope.
+- \`app.dashboard.get('Synonym')\` (HawkSearch dashboard API, read) needs the \`hawksearch:read\` scope.
+- \`app.dashboard.post/put/delete('Synonym', body)\` (writes: synonyms, redirects, banners, landing pages, …) need the \`hawksearch:write\` scope; writes are never retried.
+- \`app.context\` and \`app.onContextChange\` give the client, engine, date range, locale and theme.
+- Own backend? Send \`await app.getToken()\` as \`Authorization: Bearer ...\` and verify it there against the
+  platform's \`/.well-known/jwks.json\`. Don't use cookies: browsers block them inside the host's iframe.
+
+## Ship
+\`\`\`bash
+npm run app:deploy            # ${template === 'vanilla' ? 'upload public/' : `build and upload ${spec.build}/`} as a new version, with hawk-app.json
+npx hawk-app status           # released or not, the newest version, the approval request
+npx hawk-app open             # the app in HawkSearch, to review it and submit it for approval
+npx hawk-app clients add <id> # give a client the app (or manage clients in the Hawk Analytics portal)
+\`\`\`
+Every deploy is a new, numbered version${template === 'vanilla' ? '' : `: \`app:deploy\` builds the app with its base path set to \`/${slug}/v<n>\``},
+with the settings in \`hawk-app.json\` (scopes, origins, views, functions…).
+
+- **Not released at first.** A new app's versions are drafts: only Bridgeline staff see them. Submit a version for
+  approval in HawkSearch; once an approver releases it, the app's clients get it.
+- **Each version is reviewed.** Clients keep the released version until a new one is approved. \`npx hawk-app versions\`
+  lists every version with its status; \`npx hawk-app why <client>\` explains what a client sees.
+- **Test before release.** \`npm run app:deploy -- --alias staging\` deploys a version for an alias (e.g. new clients or a
+  branch) without touching the main line. See versions-and-aliases in the Hawk Apps docs.
+- **Clients any time.** \`npx hawk-app clients add|exclude|remove <id>\` (or the Hawk Analytics portal) applies at once,
+  without a deploy or approval, and is recorded in the app's history.
+- **Something off?** \`npx hawk-app doctor\` checks your login, the platform, the project and the bridge.
+`;
+}

package/src/credentials.mjs

@@ -1,56 +1,56 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { chmod, mkdir, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-
-/**
- * Per-user credentials, shared by every app on this machine:
- *   Windows        %APPDATA%\hawk-app\credentials.json
- *   macOS / Linux  $XDG_CONFIG_HOME/hawk-app/credentials.json (default ~/.config/hawk-app/credentials.json)
- * HAWK_APPS_CREDENTIALS_FILE overrides the location.
- */
-export function credentialsPath(env = process.env, platform = process.platform, home = homedir()) {
-    if (env.HAWK_APPS_CREDENTIALS_FILE) return env.HAWK_APPS_CREDENTIALS_FILE;
-    const base = platform === 'win32' ? env.APPDATA ?? join(home, 'AppData', 'Roaming') : env.XDG_CONFIG_HOME ?? join(home, '.config');
-    return join(base, 'hawk-app', 'credentials.json');
-}
-
-export function normalizeUrl(url) {
-    return String(url ?? '').trim().replace(/\/+$/, '');
-}
-
-/** @returns {{ platforms: Record<string, { publisherKey: string, savedAt?: string }> }} */
-export function readCredentials(path) {
-    try {
-        const data = JSON.parse(readFileSync(path, 'utf8'));
-        return { platforms: data.platforms ?? {} };
-    } catch {
-        return { platforms: {} };
-    }
-}
-
-async function writeCredentials(path, data) {
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
-    // Owner-only on macOS/Linux; on Windows the file lives in the user's own profile.
-    await chmod(path, 0o600).catch(() => undefined);
-}
-
-/** Saves the key for a platform. It doesn't choose the platform commands use (see resolveSettings). */
-export async function saveCredential(path, url, publisherKey) {
-    const data = readCredentials(path);
-    const platform = normalizeUrl(url);
-    data.platforms[platform] = { publisherKey, savedAt: new Date().toISOString() };
-    await writeCredentials(path, data);
-}
-
-/** @returns {boolean} whether a key was removed. */
-export async function removeCredential(path, url) {
-    if (!existsSync(path)) return false;
-    const data = readCredentials(path);
-    const platform = normalizeUrl(url);
-    if (!data.platforms[platform]) return false;
-    delete data.platforms[platform];
-    await writeCredentials(path, data);
-    return true;
-}
+import { existsSync, readFileSync } from 'node:fs';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * Per-user credentials, shared by every app on this machine:
+ *   Windows        %APPDATA%\hawk-app\credentials.json
+ *   macOS / Linux  $XDG_CONFIG_HOME/hawk-app/credentials.json (default ~/.config/hawk-app/credentials.json)
+ * HAWK_APPS_CREDENTIALS_FILE overrides the location.
+ */
+export function credentialsPath(env = process.env, platform = process.platform, home = homedir()) {
+    if (env.HAWK_APPS_CREDENTIALS_FILE) return env.HAWK_APPS_CREDENTIALS_FILE;
+    const base = platform === 'win32' ? env.APPDATA ?? join(home, 'AppData', 'Roaming') : env.XDG_CONFIG_HOME ?? join(home, '.config');
+    return join(base, 'hawk-app', 'credentials.json');
+}
+
+export function normalizeUrl(url) {
+    return String(url ?? '').trim().replace(/\/+$/, '');
+}
+
+/** @returns {{ platforms: Record<string, { publisherKey: string, savedAt?: string }> }} */
+export function readCredentials(path) {
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        return { platforms: data.platforms ?? {} };
+    } catch {
+        return { platforms: {} };
+    }
+}
+
+async function writeCredentials(path, data) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+    // Owner-only on macOS/Linux; on Windows the file lives in the user's own profile.
+    await chmod(path, 0o600).catch(() => undefined);
+}
+
+/** Saves the key for a platform. It doesn't choose the platform commands use (see resolveSettings). */
+export async function saveCredential(path, url, publisherKey) {
+    const data = readCredentials(path);
+    const platform = normalizeUrl(url);
+    data.platforms[platform] = { publisherKey, savedAt: new Date().toISOString() };
+    await writeCredentials(path, data);
+}
+
+/** @returns {boolean} whether a key was removed. */
+export async function removeCredential(path, url) {
+    if (!existsSync(path)) return false;
+    const data = readCredentials(path);
+    const platform = normalizeUrl(url);
+    if (!data.platforms[platform]) return false;
+    delete data.platforms[platform];
+    await writeCredentials(path, data);
+    return true;
+}