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

package/src/versions.mjs

@@ -1,102 +1,102 @@
-import { DEFAULT_ALIAS, checkAlias } from './aliases.mjs';
-
-/**
- * Versions, aliases and "why": the developer's view of who sees which version.
- *   hawk-app versions               each version with its status and the aliases on it
- *   hawk-app alias set <name> <v>   point an alias at a version that isn't approved (staff only)
- *   hawk-app alias delete <name>    delete an alias of yours (not approved, no clients on it)
- *   hawk-app why <client>           what a client's users see, and why
- */
-
-const STATUS_NOTE = {
-    draft: 'staff only',
-    waiting: 'staff only, waiting for approval',
-    rejected: 'staff only',
-    approved: '',
-};
-
-/** `hawk-app versions`: newest first, with status and aliases. */
-export async function versionsCommand({ client, manifest, log = console.log }) {
-    const { versions = [] } = await client.listVersions(manifest.slug);
-    if (!versions.length) {
-        log(`${manifest.slug} has no versions yet. Deploy one with \`npm run app:deploy\`.`);
-        return 0;
-    }
-    log(`${manifest.slug}: versions, newest first`);
-    for (const v of versions) {
-        const aliases = v.aliases?.length ? `  ${v.aliases.join(', ')}` : '';
-        const note = STATUS_NOTE[v.status] ? `  (${STATUS_NOTE[v.status]})` : '';
-        const branch = v.deployedFor ? `  deployed for ${v.deployedFor}` : '';
-        log(`  v${String(v.version).padEnd(4)} ${v.status.padEnd(9)}${aliases}${note}${branch}`);
-        if (v.status === 'rejected' && v.rejectedReason) log(`         rejected: ${v.rejectedReason}`);
-    }
-    log('Clients get the version of their alias (default without one); users see it only when it\'s approved.');
-    return 0;
-}
-
-/** `hawk-app alias set <name> <version>` / `hawk-app alias delete <name>`. */
-export async function aliasCommand({ client, manifest, sub, args = [], log = console.log }) {
-    const usage = 'Usage:\n  hawk-app alias set <name> <version>   (e.g. hawk-app alias set staging 15)\n  hawk-app alias delete <name>';
-    const slug = manifest.slug;
-    switch (sub) {
-        case 'set': {
-            const name = checkAlias(args[0], { flag: 'alias set' });
-            const version = Number(String(args[1] ?? '').replace(/^v/, ''));
-            if (!Number.isInteger(version) || version < 1) throw new Error(usage);
-            await client.setAlias(slug, name, version);
-            log(`✔ ${name} → v${version}. Clients on ${name}: only Bridgeline staff in them see it until v${version} is approved.`);
-            return 0;
-        }
-        case 'delete': {
-            const name = checkAlias(args[0], { flag: 'alias delete' });
-            await client.deleteAlias(slug, name);
-            log(`✔ Deleted ${name}.`);
-            return 0;
-        }
-        default:
-            throw new Error(usage);
-    }
-}
-
-/**
- * `hawk-app why <client>`: what the client's users see of the app, and why (the same rules as the platform's catalog):
- * the app's state and visibility, the client list, the client's alias and that version's status.
- */
-export async function whyCommand({ client, manifest, clientId, log = console.log }) {
-    if (!clientId) throw new Error('Usage: hawk-app why <client id>   (e.g. hawk-app why e3141)');
-    const app = await client.status(manifest.slug);
-    const row = (app.clients ?? []).find((c) => c.id === clientId);
-    const aliasName = row?.alias ?? DEFAULT_ALIAS;
-    const alias = (app.aliases ?? []).find((a) => a.name === aliasName);
-    const say = (verdict, ...reasons) => {
-        log(`${clientId}: ${verdict}`);
-        for (const reason of reasons) log(`  - ${reason}`);
-        return 0;
-    };
-
-    if (app.adminLocked) return say('nobody sees the app', 'an administrator locked it.');
-    if (app.status === 'Disabled') return say('nobody sees the app', 'it is disabled.');
-    if (app.visibility === 'internal') return say('its users don\'t see the app; Bridgeline staff do', 'visibility is "internal": Bridgeline staff only.');
-    if (app.visibility === 'allowList' && !row?.enabled) {
-        return say("its users don't see the app", `it isn't on the app's client list (visibility "allowList"). Add it: hawk-app clients add ${clientId}`);
-    }
-    if (app.visibility === 'all' && row && !row.enabled) {
-        return say("its users don't see the app", `it's excluded (visibility "all"). Add it back: hawk-app clients add ${clientId}`);
-    }
-    const listed = app.visibility === 'all' ? 'visibility "all": every client that isn\'t excluded' : 'it\'s on the app\'s client list';
-    if (aliasName === DEFAULT_ALIAS) {
-        if (!app.liveVersion || app.status !== 'Live') {
-            return say("its users don't see the app yet", listed, `it follows ${DEFAULT_ALIAS}, and nothing is released to everyone yet: Bridgeline staff in it see the newest version.`);
-        }
-        return say(`its users see v${app.liveVersion}`, listed, `it follows ${DEFAULT_ALIAS} (the version released to everyone).`);
-    }
-    if (!alias) return say('its users see the default version', listed, `its alias "${aliasName}" no longer exists, so it follows ${DEFAULT_ALIAS}.`);
-    if (alias.status !== 'approved') {
-        return say(
-            `its users don't see the app; Bridgeline staff in it see v${alias.version}`,
-            listed,
-            `it's on ${aliasName}, which points at v${alias.version}: ${alias.status ?? 'draft'}, not approved yet.`,
-        );
-    }
-    return say(`its users see v${alias.version}`, listed, `it's on ${aliasName}, which points at v${alias.version} (approved).`);
-}
+import { DEFAULT_ALIAS, checkAlias } from './aliases.mjs';
+
+/**
+ * Versions, aliases and "why": the developer's view of who sees which version.
+ *   hawk-app versions               each version with its status and the aliases on it
+ *   hawk-app alias set <name> <v>   point an alias at a version that isn't approved (staff only)
+ *   hawk-app alias delete <name>    delete an alias of yours (not approved, no clients on it)
+ *   hawk-app why <client>           what a client's users see, and why
+ */
+
+const STATUS_NOTE = {
+    draft: 'staff only',
+    waiting: 'staff only, waiting for approval',
+    rejected: 'staff only',
+    approved: '',
+};
+
+/** `hawk-app versions`: newest first, with status and aliases. */
+export async function versionsCommand({ client, manifest, log = console.log }) {
+    const { versions = [] } = await client.listVersions(manifest.slug);
+    if (!versions.length) {
+        log(`${manifest.slug} has no versions yet. Deploy one with \`npm run app:deploy\`.`);
+        return 0;
+    }
+    log(`${manifest.slug}: versions, newest first`);
+    for (const v of versions) {
+        const aliases = v.aliases?.length ? `  ${v.aliases.join(', ')}` : '';
+        const note = STATUS_NOTE[v.status] ? `  (${STATUS_NOTE[v.status]})` : '';
+        const branch = v.deployedFor ? `  deployed for ${v.deployedFor}` : '';
+        log(`  v${String(v.version).padEnd(4)} ${v.status.padEnd(9)}${aliases}${note}${branch}`);
+        if (v.status === 'rejected' && v.rejectedReason) log(`         rejected: ${v.rejectedReason}`);
+    }
+    log('Clients get the version of their alias (default without one); users see it only when it\'s approved.');
+    return 0;
+}
+
+/** `hawk-app alias set <name> <version>` / `hawk-app alias delete <name>`. */
+export async function aliasCommand({ client, manifest, sub, args = [], log = console.log }) {
+    const usage = 'Usage:\n  hawk-app alias set <name> <version>   (e.g. hawk-app alias set staging 15)\n  hawk-app alias delete <name>';
+    const slug = manifest.slug;
+    switch (sub) {
+        case 'set': {
+            const name = checkAlias(args[0], { flag: 'alias set' });
+            const version = Number(String(args[1] ?? '').replace(/^v/, ''));
+            if (!Number.isInteger(version) || version < 1) throw new Error(usage);
+            await client.setAlias(slug, name, version);
+            log(`✔ ${name} → v${version}. Clients on ${name}: only Bridgeline staff in them see it until v${version} is approved.`);
+            return 0;
+        }
+        case 'delete': {
+            const name = checkAlias(args[0], { flag: 'alias delete' });
+            await client.deleteAlias(slug, name);
+            log(`✔ Deleted ${name}.`);
+            return 0;
+        }
+        default:
+            throw new Error(usage);
+    }
+}
+
+/**
+ * `hawk-app why <client>`: what the client's users see of the app, and why (the same rules as the platform's catalog):
+ * the app's state and visibility, the client list, the client's alias and that version's status.
+ */
+export async function whyCommand({ client, manifest, clientId, log = console.log }) {
+    if (!clientId) throw new Error('Usage: hawk-app why <client id>   (e.g. hawk-app why e3141)');
+    const app = await client.status(manifest.slug);
+    const row = (app.clients ?? []).find((c) => c.id === clientId);
+    const aliasName = row?.alias ?? DEFAULT_ALIAS;
+    const alias = (app.aliases ?? []).find((a) => a.name === aliasName);
+    const say = (verdict, ...reasons) => {
+        log(`${clientId}: ${verdict}`);
+        for (const reason of reasons) log(`  - ${reason}`);
+        return 0;
+    };
+
+    if (app.adminLocked) return say('nobody sees the app', 'an administrator locked it.');
+    if (app.status === 'Disabled') return say('nobody sees the app', 'it is disabled.');
+    if (app.visibility === 'internal') return say('its users don\'t see the app; Bridgeline staff do', 'visibility is "internal": Bridgeline staff only.');
+    if (app.visibility === 'allowList' && !row?.enabled) {
+        return say("its users don't see the app", `it isn't on the app's client list (visibility "allowList"). Add it: hawk-app clients add ${clientId}`);
+    }
+    if (app.visibility === 'all' && row && !row.enabled) {
+        return say("its users don't see the app", `it's excluded (visibility "all"). Add it back: hawk-app clients add ${clientId}`);
+    }
+    const listed = app.visibility === 'all' ? 'visibility "all": every client that isn\'t excluded' : 'it\'s on the app\'s client list';
+    if (aliasName === DEFAULT_ALIAS) {
+        if (!app.liveVersion || app.status !== 'Live') {
+            return say("its users don't see the app yet", listed, `it follows ${DEFAULT_ALIAS}, and nothing is released to everyone yet: Bridgeline staff in it see the newest version.`);
+        }
+        return say(`its users see v${app.liveVersion}`, listed, `it follows ${DEFAULT_ALIAS} (the version released to everyone).`);
+    }
+    if (!alias) return say('its users see the default version', listed, `its alias "${aliasName}" no longer exists, so it follows ${DEFAULT_ALIAS}.`);
+    if (alias.status !== 'approved') {
+        return say(
+            `its users don't see the app; Bridgeline staff in it see v${alias.version}`,
+            listed,
+            `it's on ${aliasName}, which points at v${alias.version}: ${alias.status ?? 'draft'}, not approved yet.`,
+        );
+    }
+    return say(`its users see v${alias.version}`, listed, `it's on ${aliasName}, which points at v${alias.version} (approved).`);
+}

package/templates/next/next.config.ts

@@ -1,13 +1,13 @@
-import type { NextConfig } from 'next';
-
-// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server
-// features (no SSR, API routes or middleware). All data comes through the bridge.
-// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.
-const nextConfig: NextConfig = {
-    output: 'export',
-    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',
-    trailingSlash: true,
-    images: { unoptimized: true },
-};
-
-export default nextConfig;
+import type { NextConfig } from 'next';
+
+// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server
+// features (no SSR, API routes or middleware). All data comes through the bridge.
+// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.
+const nextConfig: NextConfig = {
+    output: 'export',
+    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',
+    trailingSlash: true,
+    images: { unoptimized: true },
+};
+
+export default nextConfig;

package/templates/next/package.json

@@ -1,26 +1,26 @@
-{
-  "name": "__SLUG__",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev -p 3100",
-    "build": "next build",
-    "app:dev": "hawk-app dev",
-    "app:deploy": "hawk-app deploy",
-    "app:audit": "npm audit --omit=dev --audit-level=high"
-  },
-  "dependencies": {
-    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
-    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
-    "next": "^16.4.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0"
-  },
-  "devDependencies": {
-    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
-    "@types/node": "^20",
-    "@types/react": "^19.1.0",
-    "@types/react-dom": "^19.1.0",
-    "typescript": "^5.6.0"
-  }
-}
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3100",
+    "build": "next build",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "dependencies": {
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "next": "^16.4.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "@types/node": "^20",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/next/src/lib/useHawkApp.ts

@@ -1,46 +1,46 @@
-'use client';
-
-import { createApp, type HawkApp, type HawkAppContext } from '@bridgeline-digital/hawk-app-bridge/client';
-import { useEffect, useState } from 'react';
-
-/** Shown when the app is opened directly instead of inside a host. */
-function notEmbeddedMessage(): string {
-    return `Open this app from the Apps page in HawkSearch. Developing locally? Add ?devUrl=${window.location.href} to the app's address in HawkSearch.`;
-}
-
-export type HawkAppState =
-    | { status: 'connecting' }
-    | { status: 'ready'; app: HawkApp; context: HawkAppContext }
-    | { status: 'error'; message: string };
-
-/** Connects to the host (the HawkSearch dashboard / Spark) once and keeps the context (client, engine, dates, theme) current. */
-export function useHawkApp(): HawkAppState {
-    const [state, setState] = useState<HawkAppState>({ status: 'connecting' });
-
-    useEffect(() => {
-        let app: HawkApp | undefined;
-        let cancelled = false;
-
-        createApp({ autoResize: true })
-            .then((connected) => {
-                if (cancelled) return connected.destroy();
-                app = connected;
-                setState({ status: 'ready', app: connected, context: connected.context });
-                connected.onContextChange((context) => setState({ status: 'ready', app: connected, context }));
-            })
-            .catch((error: { code?: string; message?: string }) => {
-                if (cancelled) return;
-                setState({
-                    status: 'error',
-                    message: error.code === 'not_embedded' ? notEmbeddedMessage() : `Could not connect to the host: ${error.message}`,
-                });
-            });
-
-        return () => {
-            cancelled = true;
-            app?.destroy();
-        };
-    }, []);
-
-    return state;
-}
+'use client';
+
+import { createApp, type HawkApp, type HawkAppContext } from '@bridgeline-digital/hawk-app-bridge/client';
+import { useEffect, useState } from 'react';
+
+/** Shown when the app is opened directly instead of inside a host. */
+function notEmbeddedMessage(): string {
+    return `Open this app from the Apps page in HawkSearch. Developing locally? Add ?devUrl=${window.location.href} to the app's address in HawkSearch.`;
+}
+
+export type HawkAppState =
+    | { status: 'connecting' }
+    | { status: 'ready'; app: HawkApp; context: HawkAppContext }
+    | { status: 'error'; message: string };
+
+/** Connects to the host (the HawkSearch dashboard / Spark) once and keeps the context (client, engine, dates, theme) current. */
+export function useHawkApp(): HawkAppState {
+    const [state, setState] = useState<HawkAppState>({ status: 'connecting' });
+
+    useEffect(() => {
+        let app: HawkApp | undefined;
+        let cancelled = false;
+
+        createApp({ autoResize: true })
+            .then((connected) => {
+                if (cancelled) return connected.destroy();
+                app = connected;
+                setState({ status: 'ready', app: connected, context: connected.context });
+                connected.onContextChange((context) => setState({ status: 'ready', app: connected, context }));
+            })
+            .catch((error: { code?: string; message?: string }) => {
+                if (cancelled) return;
+                setState({
+                    status: 'error',
+                    message: error.code === 'not_embedded' ? notEmbeddedMessage() : `Could not connect to the host: ${error.message}`,
+                });
+            });
+
+        return () => {
+            cancelled = true;
+            app?.destroy();
+        };
+    }, []);
+
+    return state;
+}

package/templates/next-mui/next.config.ts

@@ -1,13 +1,13 @@
-import type { NextConfig } from 'next';
-
-// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server
-// features (no SSR, API routes or middleware). All data comes through the bridge.
-// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.
-const nextConfig: NextConfig = {
-    output: 'export',
-    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',
-    trailingSlash: true,
-    images: { unoptimized: true },
-};
-
-export default nextConfig;
+import type { NextConfig } from 'next';
+
+// Hawk Apps are static files on the apps CDN, one folder per deploy (/<slug>/v<n>/): static export, no server
+// features (no SSR, API routes or middleware). All data comes through the bridge.
+// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>.
+const nextConfig: NextConfig = {
+    output: 'export',
+    basePath: process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__',
+    trailingSlash: true,
+    images: { unoptimized: true },
+};
+
+export default nextConfig;

package/templates/next-mui/package.json

@@ -1,31 +1,31 @@
-{
-  "name": "__SLUG__",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev -p 3100",
-    "build": "next build",
-    "app:dev": "hawk-app dev",
-    "app:deploy": "hawk-app deploy",
-    "app:audit": "npm audit --omit=dev --audit-level=high"
-  },
-  "dependencies": {
-    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
-    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
-    "@mui/icons-material": "^9.5.0",
-    "@mui/material": "^9.5.0",
-    "@mui/material-nextjs": "^9.5.0",
-    "next": "^16.4.0",
-    "react": "^19.1.0",
-    "react-dom": "^19.1.0"
-  },
-  "devDependencies": {
-    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
-    "@types/node": "^20",
-    "@types/react": "^19.1.0",
-    "@types/react-dom": "^19.1.0",
-    "typescript": "^5.6.0"
-  }
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3100",
+    "build": "next build",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "dependencies": {
+    "@bridgeline-digital/hawk-app-bridge": "^0.1.0",
+    "@bridgeline-digital/hawk-app-ui": "^0.1.0",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@mui/icons-material": "^9.5.0",
+    "@mui/material": "^9.5.0",
+    "@mui/material-nextjs": "^9.5.0",
+    "next": "^16.4.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "@types/node": "^20",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "typescript": "^5.6.0"
+  }
 }

package/templates/next-mui/src/app/layout.tsx

@@ -1,20 +1,20 @@
-// Montserrat, Spark's font, bundled with the app (no request to Google Fonts at build or run time).
-import '@bridgeline-digital/hawk-app-ui/fonts';
-import { AppRouterCacheProvider } from '@mui/material-nextjs/v16-appRouter';
-import type { Metadata } from 'next';
-import Providers from './providers';
-
-export const metadata: Metadata = { title: '__NAME__' };
-
-export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
-    return (
-        <html lang="en">
-            <body>
-                {/* Puts MUI's styles into the exported HTML, so the page doesn't flash unstyled. */}
-                <AppRouterCacheProvider>
-                    <Providers>{children}</Providers>
-                </AppRouterCacheProvider>
-            </body>
-        </html>
-    );
+// Montserrat, Spark's font, bundled with the app (no request to Google Fonts at build or run time).
+import '@bridgeline-digital/hawk-app-ui/fonts';
+import { AppRouterCacheProvider } from '@mui/material-nextjs/v16-appRouter';
+import type { Metadata } from 'next';
+import Providers from './providers';
+
+export const metadata: Metadata = { title: '__NAME__' };
+
+export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
+    return (
+        <html lang="en">
+            <body>
+                {/* Puts MUI's styles into the exported HTML, so the page doesn't flash unstyled. */}
+                <AppRouterCacheProvider>
+                    <Providers>{children}</Providers>
+                </AppRouterCacheProvider>
+            </body>
+        </html>
+    );
 }