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

package/src/app-icon.mjs

@@ -1,82 +1,82 @@
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { extname, resolve } from 'node:path';
-
-// The app's icon: an .svg or .png file next to hawk-app.json ("icon": "icon.svg"). Deploy uploads it into every
-// version as _hawk/icon.svg or _hawk/icon.png, so it's reviewed and released with the version. Hosts draw an SVG in
-// their own text color (as a CSS mask: only its shape counts, not its colors) and show a PNG as is. Without one, hosts
-// show their default icon.
-
-/** A relative path to an .svg or .png file: letters, digits, . _ - and /, no "..", at most 200 characters. */
-export const ICON_PATH = /^(?!.*\.\.)[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*\.(svg|png)$/i;
-export const ICON_PATH_HINT = 'an .svg or .png file next to hawk-app.json, e.g. "icon.svg"';
-
-export const MAX_SVG_BYTES = 32 * 1024;
-export const MAX_PNG_BYTES = 256 * 1024;
-export const MIN_PNG_SIZE = 64;
-export const MAX_PNG_SIZE = 1024;
-
-/** The icon `create` and `init` add: a neutral app glyph (four rounded squares), one color, square. */
-export const DEFAULT_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
-  <rect x="3" y="3" width="8" height="8" rx="2"/>
-  <rect x="13" y="3" width="8" height="8" rx="2"/>
-  <rect x="3" y="13" width="8" height="8" rx="2"/>
-  <rect x="13" y="13" width="8" height="8" rx="2"/>
-</svg>
-`;
-
-/** Where deploy puts the icon in a version: _hawk/icon.svg or _hawk/icon.png. */
-export function iconUploadPath(icon) {
-    return `_hawk/icon${extname(icon).toLowerCase()}`;
-}
-
-/**
- * Checks the icon file hawk-app.json names (when it names one): there, the right type and size, square. Returns the
- * file to upload ({ path: _hawk/icon.*, size, data }), with errors and warnings.
- */
-export async function checkIcon(projectDir, icon) {
-    const errors = [];
-    const warnings = [];
-    if (icon === undefined || icon === null || icon === '') return { errors, warnings, file: null };
-    if (typeof icon !== 'string' || !ICON_PATH.test(icon)) {
-        return { errors: [`icon must be ${ICON_PATH_HINT}.`], warnings, file: null };
-    }
-    const full = resolve(projectDir, icon);
-    if (!existsSync(full)) {
-        return { errors: [`icon: ${icon} doesn't exist next to hawk-app.json. Add it, or leave "icon" out for the hosts' default icon.`], warnings, file: null };
-    }
-    const data = await readFile(full);
-    if (extname(icon).toLowerCase() === '.svg') {
-        if (data.length > MAX_SVG_BYTES) errors.push(`icon: ${icon} is ${Math.ceil(data.length / 1024)} KB; an SVG icon can be at most ${MAX_SVG_BYTES / 1024} KB.`);
-        const text = data.toString('utf8');
-        const root = /<svg\b[^>]*>/i.exec(text)?.[0];
-        if (!root) {
-            errors.push(`icon: ${icon} isn't an SVG (no <svg> element).`);
-        } else {
-            const box = /\bviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)\s*["']/i.exec(root);
-            if (!box) warnings.push(`icon: ${icon} has no viewBox: hosts may draw it at the wrong size. Give it a square one, e.g. viewBox="0 0 24 24".`);
-            else if (Math.abs(Number(box[1]) - Number(box[2])) > 0.001) warnings.push(`icon: ${icon} isn't square (viewBox ${box[1]}×${box[2]}): hosts fit it in a square.`);
-        }
-        if (/<(image|foreignObject)\b/i.test(text)) {
-            warnings.push(`icon: ${icon} contains <image> or <foreignObject>: hosts draw only an SVG icon's shape, in their own color. For a picture, use a .png icon.`);
-        }
-    } else {
-        if (data.length > MAX_PNG_BYTES) errors.push(`icon: ${icon} is ${Math.ceil(data.length / 1024)} KB; a PNG icon can be at most ${MAX_PNG_BYTES / 1024} KB.`);
-        const size = pngSize(data);
-        if (!size) {
-            errors.push(`icon: ${icon} isn't a PNG.`);
-        } else if (size.width !== size.height) {
-            errors.push(`icon: ${icon} is ${size.width}×${size.height}; a PNG icon must be square.`);
-        } else if (size.width < MIN_PNG_SIZE || size.width > MAX_PNG_SIZE) {
-            errors.push(`icon: ${icon} is ${size.width}×${size.height}; a PNG icon must be ${MIN_PNG_SIZE}–${MAX_PNG_SIZE} px (256×256 is a good size).`);
-        }
-    }
-    return { errors, warnings, file: errors.length ? null : { path: iconUploadPath(icon), size: data.length, data } };
-}
-
-/** A PNG's width and height from its IHDR chunk; null when it isn't a PNG. */
-export function pngSize(data) {
-    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
-    if (data.length < 24 || !data.subarray(0, 8).equals(signature) || data.toString('ascii', 12, 16) !== 'IHDR') return null;
-    return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
-}
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { extname, resolve } from 'node:path';
+
+// The app's icon: an .svg or .png file next to hawk-app.json ("icon": "icon.svg"). Deploy uploads it into every
+// version as _hawk/icon.svg or _hawk/icon.png, so it's reviewed and released with the version. Hosts draw an SVG in
+// their own text color (as a CSS mask: only its shape counts, not its colors) and show a PNG as is. Without one, hosts
+// show their default icon.
+
+/** A relative path to an .svg or .png file: letters, digits, . _ - and /, no "..", at most 200 characters. */
+export const ICON_PATH = /^(?!.*\.\.)[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*\.(svg|png)$/i;
+export const ICON_PATH_HINT = 'an .svg or .png file next to hawk-app.json, e.g. "icon.svg"';
+
+export const MAX_SVG_BYTES = 32 * 1024;
+export const MAX_PNG_BYTES = 256 * 1024;
+export const MIN_PNG_SIZE = 64;
+export const MAX_PNG_SIZE = 1024;
+
+/** The icon `create` and `init` add: a neutral app glyph (four rounded squares), one color, square. */
+export const DEFAULT_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor">
+  <rect x="3" y="3" width="8" height="8" rx="2"/>
+  <rect x="13" y="3" width="8" height="8" rx="2"/>
+  <rect x="3" y="13" width="8" height="8" rx="2"/>
+  <rect x="13" y="13" width="8" height="8" rx="2"/>
+</svg>
+`;
+
+/** Where deploy puts the icon in a version: _hawk/icon.svg or _hawk/icon.png. */
+export function iconUploadPath(icon) {
+    return `_hawk/icon${extname(icon).toLowerCase()}`;
+}
+
+/**
+ * Checks the icon file hawk-app.json names (when it names one): there, the right type and size, square. Returns the
+ * file to upload ({ path: _hawk/icon.*, size, data }), with errors and warnings.
+ */
+export async function checkIcon(projectDir, icon) {
+    const errors = [];
+    const warnings = [];
+    if (icon === undefined || icon === null || icon === '') return { errors, warnings, file: null };
+    if (typeof icon !== 'string' || !ICON_PATH.test(icon)) {
+        return { errors: [`icon must be ${ICON_PATH_HINT}.`], warnings, file: null };
+    }
+    const full = resolve(projectDir, icon);
+    if (!existsSync(full)) {
+        return { errors: [`icon: ${icon} doesn't exist next to hawk-app.json. Add it, or leave "icon" out for the hosts' default icon.`], warnings, file: null };
+    }
+    const data = await readFile(full);
+    if (extname(icon).toLowerCase() === '.svg') {
+        if (data.length > MAX_SVG_BYTES) errors.push(`icon: ${icon} is ${Math.ceil(data.length / 1024)} KB; an SVG icon can be at most ${MAX_SVG_BYTES / 1024} KB.`);
+        const text = data.toString('utf8');
+        const root = /<svg\b[^>]*>/i.exec(text)?.[0];
+        if (!root) {
+            errors.push(`icon: ${icon} isn't an SVG (no <svg> element).`);
+        } else {
+            const box = /\bviewBox\s*=\s*["']\s*[-\d.]+[\s,]+[-\d.]+[\s,]+([\d.]+)[\s,]+([\d.]+)\s*["']/i.exec(root);
+            if (!box) warnings.push(`icon: ${icon} has no viewBox: hosts may draw it at the wrong size. Give it a square one, e.g. viewBox="0 0 24 24".`);
+            else if (Math.abs(Number(box[1]) - Number(box[2])) > 0.001) warnings.push(`icon: ${icon} isn't square (viewBox ${box[1]}×${box[2]}): hosts fit it in a square.`);
+        }
+        if (/<(image|foreignObject)\b/i.test(text)) {
+            warnings.push(`icon: ${icon} contains <image> or <foreignObject>: hosts draw only an SVG icon's shape, in their own color. For a picture, use a .png icon.`);
+        }
+    } else {
+        if (data.length > MAX_PNG_BYTES) errors.push(`icon: ${icon} is ${Math.ceil(data.length / 1024)} KB; a PNG icon can be at most ${MAX_PNG_BYTES / 1024} KB.`);
+        const size = pngSize(data);
+        if (!size) {
+            errors.push(`icon: ${icon} isn't a PNG.`);
+        } else if (size.width !== size.height) {
+            errors.push(`icon: ${icon} is ${size.width}×${size.height}; a PNG icon must be square.`);
+        } else if (size.width < MIN_PNG_SIZE || size.width > MAX_PNG_SIZE) {
+            errors.push(`icon: ${icon} is ${size.width}×${size.height}; a PNG icon must be ${MIN_PNG_SIZE}–${MAX_PNG_SIZE} px (256×256 is a good size).`);
+        }
+    }
+    return { errors, warnings, file: errors.length ? null : { path: iconUploadPath(icon), size: data.length, data } };
+}
+
+/** A PNG's width and height from its IHDR chunk; null when it isn't a PNG. */
+export function pngSize(data) {
+    const signature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    if (data.length < 24 || !data.subarray(0, 8).equals(signature) || data.toString('ascii', 12, 16) !== 'IHDR') return null;
+    return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+}

package/src/channel.mjs

@@ -1,116 +1,116 @@
-// Release channels of the Hawk Apps packages. `latest` (from main) is stable and matches the prod platform; `dev`
-// (prereleases from the dev branch, e.g. 0.7.0-dev.20261014…) has features that may need the dev platform.
-//   - `hawk-app create` from a dev CLI (npx …-cli@dev create) makes a dev app: the Hawk packages on the `dev` dist-tag
-//     (the vanilla template's CDN import too), so it gets the dev bridge, not the latest one the template pins.
-//   - `hawk-app upgrade --channel latest|dev` moves an app between channels.
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-
-export const BRIDGE = '@bridgeline-digital/hawk-app-bridge';
-export const CLI = '@bridgeline-digital/hawk-app-cli';
-/** The UI kit (next-mui apps): released with the bridge and CLI, so it follows the same channel. */
-export const UI = '@bridgeline-digital/hawk-app-ui';
-export const HAWK_PACKAGES = [BRIDGE, UI, CLI];
-export const CHANNELS = ['latest', 'dev'];
-
-/**
- * The vanilla template's imports from the CDN, the bridge and the UI kit (one version: they're released together): by
- * minor (`@0.6/`) or by dist-tag (`@dev/`).
- */
-export const CDN_BRIDGE = /(hawk-app-(?:bridge|ui)@)([0-9]+\.[0-9]+|dev)(\/)/;
-
-/** The vanilla template's files that load from the CDN: the bridge and the kit's elements (app.js), the kit's stylesheet (index.html). */
-export const CDN_FILES = [join('public', 'app.js'), join('public', 'index.html')];
-
-/** `text` with every CDN import of the bridge and the UI kit at `version` (a minor or a dist-tag). */
-export const pointCdn = (text, version) => text.replace(new RegExp(CDN_BRIDGE.source, 'g'), `$1${version}$3`);
-
-/** Points the app's CDN files (those that exist) at `version`; returns the files changed. */
-export async function writeCdnFiles(dir, version) {
-    const changed = [];
-    for (const file of CDN_FILES) {
-        const path = join(dir, file);
-        if (!existsSync(path)) continue;
-        const text = await readFile(path, 'utf8');
-        const next = pointCdn(text, version);
-        if (next !== text) {
-            await writeFile(path, next);
-            changed.push(file);
-        }
-    }
-    return changed;
-}
-
-const isPrerelease = (version) => /^\d+\.\d+\.\d+-/.test(String(version ?? '').trim());
-
-/** This CLI's version, e.g. 0.7.0 or 0.8.0-dev.20261014120000. */
-export const cliVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
-
-/** The channel this CLI came from: a prerelease is a dev build. */
-export const cliChannel = (version = cliVersion()) => (isPrerelease(version) ? 'dev' : 'latest');
-
-/** A package.json version spec on the dev channel: the `dev` dist-tag or a prerelease range. */
-export const isDevSpec = (spec) => {
-    const text = String(spec ?? '').trim();
-    return text === 'dev' || isPrerelease(text.replace(/^[\^~>=v\s]+/, ''));
-};
-
-/** The app's channel from its package.json (dev when any Hawk package is on dev), or null without them. */
-export function appChannel(pkg) {
-    const specs = HAWK_PACKAGES.map((name) => pkg?.dependencies?.[name] ?? pkg?.devDependencies?.[name]).filter(Boolean);
-    if (!specs.length) return null;
-    return specs.some(isDevSpec) ? 'dev' : 'latest';
-}
-
-/** The version npm's `latest` tag points at, e.g. "0.6.0"; null when npm can't be asked (offline, no npm). */
-export function npmLatest(name, run = spawnSync) {
-    const result = run('npm', ['view', `${name}@latest`, 'version'], { encoding: 'utf8', shell: process.platform === 'win32' });
-    const version = String(result?.stdout ?? '').trim().split(/\s+/).pop();
-    return result?.status === 0 && /^\d+\.\d+\.\d+$/.test(version) ? version : null;
-}
-
-/**
- * The changes that put a package.json (and the vanilla CDN import) on `channel`: [{ name, section, from, to }] and
- * { from, to } for the CDN. `latest` uses npm's latest version (`fallback` when npm can't be asked: the template's).
- */
-export function planChannel({ pkg, appJs, channel, latestVersion }) {
-    if (!CHANNELS.includes(channel)) throw new Error(`--channel must be latest or dev, not "${channel}".`);
-    const dependencies = [];
-    for (const name of HAWK_PACKAGES) {
-        const section = ['dependencies', 'devDependencies'].find((s) => pkg?.[s]?.[name] !== undefined);
-        if (!section) continue;
-        const from = pkg[section][name];
-        let to;
-        if (channel === 'dev') {
-            to = 'dev';
-        } else {
-            const version = latestVersion(name);
-            if (!version) throw new Error(`Couldn't find the latest version of ${name} on npm. Check your connection and try again.`);
-            to = `^${version}`;
-        }
-        if (from !== to) dependencies.push({ name, section, from, to });
-    }
-    let cdn = null;
-    const current = appJs ? CDN_BRIDGE.exec(appJs)?.[2] : null;
-    if (current) {
-        const version = channel === 'dev' ? 'dev' : latestVersion(BRIDGE)?.split('.').slice(0, 2).join('.');
-        if (!version) throw new Error(`Couldn't find the latest version of ${BRIDGE} on npm. Check your connection and try again.`);
-        if (current !== version) cdn = { from: current, to: version };
-    }
-    return { channel, dependencies, cdn };
-}
-
-/** Applies planChannel's changes to the package.json object and app.js text; returns the new app.js text. */
-export function applyChannel(plan, pkg, appJs) {
-    for (const { name, section, to } of plan.dependencies) pkg[section][name] = to;
-    return plan.cdn && appJs ? pointCdn(appJs, plan.cdn.to) : appJs;
-}
-
-/** What a dev app needs to know (create and upgrade print it). */
-export const DEV_CHANNEL_NOTE = [
-    'This app is on the dev channel: the bridge, the UI kit and the CLI follow their newest dev builds (the `dev` tag on npm).',
-    "Dev features may need the dev platform (the default): don't deploy it to prod until they're released.",
-    'When they are, move it to the released versions: npx hawk-app upgrade --channel latest --yes',
-];
+// Release channels of the Hawk Apps packages. `latest` (from main) is stable and matches the prod platform; `dev`
+// (prereleases from the dev branch, e.g. 0.7.0-dev.20261014…) has features that may need the dev platform.
+//   - `hawk-app create` from a dev CLI (npx …-cli@dev create) makes a dev app: the Hawk packages on the `dev` dist-tag
+//     (the vanilla template's CDN import too), so it gets the dev bridge, not the latest one the template pins.
+//   - `hawk-app upgrade --channel latest|dev` moves an app between channels.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export const BRIDGE = '@bridgeline-digital/hawk-app-bridge';
+export const CLI = '@bridgeline-digital/hawk-app-cli';
+/** The UI kit (next-mui apps): released with the bridge and CLI, so it follows the same channel. */
+export const UI = '@bridgeline-digital/hawk-app-ui';
+export const HAWK_PACKAGES = [BRIDGE, UI, CLI];
+export const CHANNELS = ['latest', 'dev'];
+
+/**
+ * The vanilla template's imports from the CDN, the bridge and the UI kit (one version: they're released together): by
+ * minor (`@0.6/`) or by dist-tag (`@dev/`).
+ */
+export const CDN_BRIDGE = /(hawk-app-(?:bridge|ui)@)([0-9]+\.[0-9]+|dev)(\/)/;
+
+/** The vanilla template's files that load from the CDN: the bridge and the kit's elements (app.js), the kit's stylesheet (index.html). */
+export const CDN_FILES = [join('public', 'app.js'), join('public', 'index.html')];
+
+/** `text` with every CDN import of the bridge and the UI kit at `version` (a minor or a dist-tag). */
+export const pointCdn = (text, version) => text.replace(new RegExp(CDN_BRIDGE.source, 'g'), `$1${version}$3`);
+
+/** Points the app's CDN files (those that exist) at `version`; returns the files changed. */
+export async function writeCdnFiles(dir, version) {
+    const changed = [];
+    for (const file of CDN_FILES) {
+        const path = join(dir, file);
+        if (!existsSync(path)) continue;
+        const text = await readFile(path, 'utf8');
+        const next = pointCdn(text, version);
+        if (next !== text) {
+            await writeFile(path, next);
+            changed.push(file);
+        }
+    }
+    return changed;
+}
+
+const isPrerelease = (version) => /^\d+\.\d+\.\d+-/.test(String(version ?? '').trim());
+
+/** This CLI's version, e.g. 0.7.0 or 0.8.0-dev.20261014120000. */
+export const cliVersion = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/** The channel this CLI came from: a prerelease is a dev build. */
+export const cliChannel = (version = cliVersion()) => (isPrerelease(version) ? 'dev' : 'latest');
+
+/** A package.json version spec on the dev channel: the `dev` dist-tag or a prerelease range. */
+export const isDevSpec = (spec) => {
+    const text = String(spec ?? '').trim();
+    return text === 'dev' || isPrerelease(text.replace(/^[\^~>=v\s]+/, ''));
+};
+
+/** The app's channel from its package.json (dev when any Hawk package is on dev), or null without them. */
+export function appChannel(pkg) {
+    const specs = HAWK_PACKAGES.map((name) => pkg?.dependencies?.[name] ?? pkg?.devDependencies?.[name]).filter(Boolean);
+    if (!specs.length) return null;
+    return specs.some(isDevSpec) ? 'dev' : 'latest';
+}
+
+/** The version npm's `latest` tag points at, e.g. "0.6.0"; null when npm can't be asked (offline, no npm). */
+export function npmLatest(name, run = spawnSync) {
+    const result = run('npm', ['view', `${name}@latest`, 'version'], { encoding: 'utf8', shell: process.platform === 'win32' });
+    const version = String(result?.stdout ?? '').trim().split(/\s+/).pop();
+    return result?.status === 0 && /^\d+\.\d+\.\d+$/.test(version) ? version : null;
+}
+
+/**
+ * The changes that put a package.json (and the vanilla CDN import) on `channel`: [{ name, section, from, to }] and
+ * { from, to } for the CDN. `latest` uses npm's latest version (`fallback` when npm can't be asked: the template's).
+ */
+export function planChannel({ pkg, appJs, channel, latestVersion }) {
+    if (!CHANNELS.includes(channel)) throw new Error(`--channel must be latest or dev, not "${channel}".`);
+    const dependencies = [];
+    for (const name of HAWK_PACKAGES) {
+        const section = ['dependencies', 'devDependencies'].find((s) => pkg?.[s]?.[name] !== undefined);
+        if (!section) continue;
+        const from = pkg[section][name];
+        let to;
+        if (channel === 'dev') {
+            to = 'dev';
+        } else {
+            const version = latestVersion(name);
+            if (!version) throw new Error(`Couldn't find the latest version of ${name} on npm. Check your connection and try again.`);
+            to = `^${version}`;
+        }
+        if (from !== to) dependencies.push({ name, section, from, to });
+    }
+    let cdn = null;
+    const current = appJs ? CDN_BRIDGE.exec(appJs)?.[2] : null;
+    if (current) {
+        const version = channel === 'dev' ? 'dev' : latestVersion(BRIDGE)?.split('.').slice(0, 2).join('.');
+        if (!version) throw new Error(`Couldn't find the latest version of ${BRIDGE} on npm. Check your connection and try again.`);
+        if (current !== version) cdn = { from: current, to: version };
+    }
+    return { channel, dependencies, cdn };
+}
+
+/** Applies planChannel's changes to the package.json object and app.js text; returns the new app.js text. */
+export function applyChannel(plan, pkg, appJs) {
+    for (const { name, section, to } of plan.dependencies) pkg[section][name] = to;
+    return plan.cdn && appJs ? pointCdn(appJs, plan.cdn.to) : appJs;
+}
+
+/** What a dev app needs to know (create and upgrade print it). */
+export const DEV_CHANNEL_NOTE = [
+    'This app is on the dev channel: the bridge, the UI kit and the CLI follow their newest dev builds (the `dev` tag on npm).',
+    "Dev features may need the dev platform (the default): don't deploy it to prod until they're released.",
+    'When they are, move it to the released versions: npx hawk-app upgrade --channel latest --yes',
+];