@cats-inc/cats-platform 0.1.0

package/scripts/shared/generate-electron-icons.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { Icns, IcnsImage } from '@fiahfy/icns';
+import pngToIco from 'png-to-ico';
+import sharp from 'sharp';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = dirname(SCRIPT_PATH);
+const PROJECT_ROOT = resolve(SCRIPT_DIR, '..', '..');
+const DEFAULT_INPUT = resolve(PROJECT_ROOT, 'assets', 'app-icon-silhouette.svg');
+const DEFAULT_ASSETS_ROOT = resolve(PROJECT_ROOT, 'assets');
+const DEFAULT_BUILD_RESOURCES_DIR = resolve(DEFAULT_ASSETS_ROOT, 'build');
+const DEFAULT_ICON_SHAPE = 'circle';
+const SUPPORTED_ICON_SHAPES = new Set(['square', 'circle']);
+
+const LINUX_ICON_SIZES = [16, 24, 32, 48, 64, 128, 256, 512];
+const ICO_SIZES = [16, 24, 32, 48, 64, 128, 256];
+const ICNS_VARIANTS = [
+  { type: 'icp4', size: 16 },
+  { type: 'ic11', size: 32 },
+  { type: 'icp5', size: 32 },
+  { type: 'ic12', size: 64 },
+  { type: 'icp6', size: 64 },
+  { type: 'ic07', size: 128 },
+  { type: 'ic13', size: 256 },
+  { type: 'ic08', size: 256 },
+  { type: 'ic14', size: 512 },
+  { type: 'ic09', size: 512 },
+  { type: 'ic10', size: 1024 },
+];
+
+function printHelp() {
+  process.stdout.write(`Usage: node scripts/shared/generate-electron-icons.mjs [options]
+
+Generate cross-platform Electron app and tray icons from a single SVG source.
+
+Options:
+  --input <path>               Source SVG. Defaults to assets/app-icon-silhouette.svg
+  --assets-root <path>         Asset root for tray outputs. Defaults to assets/
+  --build-resources <path>     Build-resource root for app icons. Defaults to assets/build
+  --shape <square|circle>      Output mask shape. Defaults to circle
+  --help                       Show this help text.
+`);
+}
+
+function normalizeIconShape(value) {
+  if (!value) {
+    return DEFAULT_ICON_SHAPE;
+  }
+  if (!SUPPORTED_ICON_SHAPES.has(value)) {
+    throw new Error(`Unsupported icon shape: ${value}`);
+  }
+  return value;
+}
+
+function parseArgs(argv) {
+  let inputSvgPath = DEFAULT_INPUT;
+  let assetsRoot = DEFAULT_ASSETS_ROOT;
+  let buildResourcesDir = DEFAULT_BUILD_RESOURCES_DIR;
+  let iconShape = DEFAULT_ICON_SHAPE;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--help' || value === '-h') {
+      return {
+        help: true,
+        inputSvgPath,
+        assetsRoot,
+        buildResourcesDir,
+        iconShape,
+      };
+    }
+    if (value === '--input') {
+      inputSvgPath = resolve(PROJECT_ROOT, argv[index + 1] ?? '');
+      index += 1;
+      continue;
+    }
+    if (value === '--assets-root') {
+      assetsRoot = resolve(PROJECT_ROOT, argv[index + 1] ?? '');
+      index += 1;
+      continue;
+    }
+    if (value === '--build-resources') {
+      buildResourcesDir = resolve(PROJECT_ROOT, argv[index + 1] ?? '');
+      index += 1;
+      continue;
+    }
+    if (value === '--shape') {
+      iconShape = normalizeIconShape(argv[index + 1] ?? '');
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${value}`);
+  }
+
+  return {
+    help: false,
+    inputSvgPath,
+    assetsRoot,
+    buildResourcesDir,
+    iconShape,
+  };
+}
+
+function toProjectRelative(pathValue) {
+  return relative(PROJECT_ROOT, pathValue).replaceAll('\\', '/');
+}
+
+async function writeBuffer(filePath, value) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, value);
+}
+
+async function rasterizeSvgPng(svgBuffer, size) {
+  return sharp(svgBuffer, { density: 1024 })
+    .resize(size, size, { fit: 'contain' })
+    .ensureAlpha()
+    .png()
+    .toBuffer();
+}
+
+function buildCircleMask(size) {
+  return Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}"><circle cx="${size / 2}" cy="${size / 2}" r="${size / 2}" fill="#fff" /></svg>`,
+  );
+}
+
+async function applyIconShapeMask(pngBuffer, size, iconShape) {
+  if (iconShape === 'square') {
+    return pngBuffer;
+  }
+
+  return sharp(pngBuffer)
+    .composite([
+      {
+        input: buildCircleMask(size),
+        blend: 'dest-in',
+      },
+    ])
+    .png()
+    .toBuffer();
+}
+
+async function renderSvgPng(svgBuffer, size, iconShape) {
+  const pngBuffer = await rasterizeSvgPng(svgBuffer, size);
+  return applyIconShapeMask(pngBuffer, size, iconShape);
+}
+
+function pixelOffset(pixelIndex) {
+  return pixelIndex * 4;
+}
+
+function rgbaDistance(rawBuffer, leftOffset, rightOffset) {
+  return Math.abs(rawBuffer[leftOffset] - rawBuffer[rightOffset])
+    + Math.abs(rawBuffer[leftOffset + 1] - rawBuffer[rightOffset + 1])
+    + Math.abs(rawBuffer[leftOffset + 2] - rawBuffer[rightOffset + 2])
+    + Math.abs(rawBuffer[leftOffset + 3] - rawBuffer[rightOffset + 3]);
+}
+
+function enqueueBackgroundPixel(backgroundMask, queue, pixelIndex) {
+  if (backgroundMask[pixelIndex]) {
+    return;
+  }
+  backgroundMask[pixelIndex] = 1;
+  queue.push(pixelIndex);
+}
+
+function buildEdgeConnectedBackgroundMask(data, width, height) {
+  const backgroundMask = new Uint8Array(width * height);
+  const queue = [];
+
+  for (let x = 0; x < width; x += 1) {
+    enqueueBackgroundPixel(backgroundMask, queue, x);
+    enqueueBackgroundPixel(backgroundMask, queue, ((height - 1) * width) + x);
+  }
+  for (let y = 1; y < height - 1; y += 1) {
+    enqueueBackgroundPixel(backgroundMask, queue, y * width);
+    enqueueBackgroundPixel(backgroundMask, queue, (y * width) + width - 1);
+  }
+
+  for (let cursor = 0; cursor < queue.length; cursor += 1) {
+    const pixelIndex = queue[cursor];
+    const x = pixelIndex % width;
+    const y = Math.floor(pixelIndex / width);
+    const sourceOffset = pixelOffset(pixelIndex);
+    const neighborIndexes = [
+      x > 0 ? pixelIndex - 1 : null,
+      x < width - 1 ? pixelIndex + 1 : null,
+      y > 0 ? pixelIndex - width : null,
+      y < height - 1 ? pixelIndex + width : null,
+    ];
+
+    for (const neighborIndex of neighborIndexes) {
+      if (neighborIndex === null || backgroundMask[neighborIndex]) {
+        continue;
+      }
+      const neighborOffset = pixelOffset(neighborIndex);
+      if (
+        data[neighborOffset + 3] === 0
+        || rgbaDistance(data, sourceOffset, neighborOffset) <= 64
+      ) {
+        enqueueBackgroundPixel(backgroundMask, queue, neighborIndex);
+      }
+    }
+  }
+
+  return backgroundMask;
+}
+
+async function renderTrayTemplate(svgBuffer, size, iconShape) {
+  const { data, info } = await sharp(svgBuffer, { density: 1024 })
+    .resize(size, size, { fit: 'contain' })
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const output = Buffer.alloc(data.length);
+  const backgroundMask = buildEdgeConnectedBackgroundMask(data, info.width, info.height);
+
+  for (let index = 0; index < data.length; index += 4) {
+    const pixelIndex = index / 4;
+    const alpha = data[index + 3];
+    if (alpha === 0 || backgroundMask[pixelIndex]) {
+      continue;
+    }
+    output[index] = 0;
+    output[index + 1] = 0;
+    output[index + 2] = 0;
+    output[index + 3] = alpha;
+  }
+
+  const templatePngBuffer = await sharp(output, {
+    raw: {
+      width: info.width,
+      height: info.height,
+      channels: 4,
+    },
+  }).png().toBuffer();
+
+  return applyIconShapeMask(templatePngBuffer, size, iconShape);
+}
+
+function buildIcns(pngBuffersBySize) {
+  const icns = new Icns();
+  for (const variant of ICNS_VARIANTS) {
+    const imageBuffer = pngBuffersBySize.get(variant.size);
+    if (!imageBuffer) {
+      throw new Error(`Missing PNG buffer for ICNS size ${variant.size}`);
+    }
+    icns.append(IcnsImage.fromPNG(imageBuffer, variant.type));
+  }
+  return icns.data;
+}
+
+export async function generateElectronIcons(options = {}) {
+  const inputSvgPath = options.inputSvgPath
+    ? resolve(PROJECT_ROOT, options.inputSvgPath)
+    : DEFAULT_INPUT;
+  const assetsRoot = options.assetsRoot
+    ? resolve(PROJECT_ROOT, options.assetsRoot)
+    : DEFAULT_ASSETS_ROOT;
+  const buildResourcesDir = options.buildResourcesDir
+    ? resolve(PROJECT_ROOT, options.buildResourcesDir)
+    : DEFAULT_BUILD_RESOURCES_DIR;
+  const iconShape = normalizeIconShape(options.iconShape);
+  const linuxIconDir = resolve(buildResourcesDir, 'icons', 'linux');
+
+  const svgBuffer = await readFile(inputSvgPath);
+  const pngBuffersBySize = new Map();
+
+  for (const size of new Set([
+    ...LINUX_ICON_SIZES,
+    ...ICO_SIZES,
+    1024,
+  ])) {
+    pngBuffersBySize.set(size, await renderSvgPng(svgBuffer, size, iconShape));
+  }
+
+  await rm(linuxIconDir, { recursive: true, force: true });
+  await mkdir(linuxIconDir, { recursive: true });
+
+  const linuxIcons = {};
+  for (const size of LINUX_ICON_SIZES) {
+    const filePath = resolve(linuxIconDir, `${size}x${size}.png`);
+    await writeBuffer(filePath, pngBuffersBySize.get(size));
+    linuxIcons[size] = toProjectRelative(filePath);
+  }
+
+  const icoBuffer = await pngToIco(ICO_SIZES.map((size) => pngBuffersBySize.get(size)));
+  const icnsBuffer = buildIcns(pngBuffersBySize);
+  const appPngPath = resolve(buildResourcesDir, 'icon.png');
+  const iconIcoPath = resolve(buildResourcesDir, 'icon.ico');
+  const installerIconPath = resolve(buildResourcesDir, 'installerIcon.ico');
+  const uninstallerIconPath = resolve(buildResourcesDir, 'uninstallerIcon.ico');
+  const installerHeaderIconPath = resolve(buildResourcesDir, 'installerHeaderIcon.ico');
+  const iconIcnsPath = resolve(buildResourcesDir, 'icon.icns');
+  const trayIconPath = resolve(assetsRoot, 'tray-icon.png');
+  const trayIcon2xPath = resolve(assetsRoot, 'tray-icon@2x.png');
+  const trayTemplatePath = resolve(assetsRoot, 'tray-iconTemplate.png');
+  const trayTemplate2xPath = resolve(assetsRoot, 'tray-iconTemplate@2x.png');
+  const manifestPath = resolve(buildResourcesDir, 'icon-manifest.json');
+
+  await writeBuffer(appPngPath, pngBuffersBySize.get(512));
+  await writeBuffer(iconIcoPath, icoBuffer);
+  await writeBuffer(installerIconPath, icoBuffer);
+  await writeBuffer(uninstallerIconPath, icoBuffer);
+  await writeBuffer(installerHeaderIconPath, icoBuffer);
+  await writeBuffer(iconIcnsPath, icnsBuffer);
+  await writeBuffer(trayIconPath, pngBuffersBySize.get(32));
+  await writeBuffer(trayIcon2xPath, pngBuffersBySize.get(64));
+  await writeBuffer(trayTemplatePath, await renderTrayTemplate(svgBuffer, 16, iconShape));
+  await writeBuffer(trayTemplate2xPath, await renderTrayTemplate(svgBuffer, 32, iconShape));
+
+  const manifest = {
+    sourceSvg: toProjectRelative(inputSvgPath),
+    shape: iconShape,
+    app: {
+      png: toProjectRelative(appPngPath),
+      ico: toProjectRelative(iconIcoPath),
+      icns: toProjectRelative(iconIcnsPath),
+      installerIcon: toProjectRelative(installerIconPath),
+      uninstallerIcon: toProjectRelative(uninstallerIconPath),
+      installerHeaderIcon: toProjectRelative(installerHeaderIconPath),
+      linuxIcons,
+    },
+    tray: {
+      default: toProjectRelative(trayIconPath),
+      retina: toProjectRelative(trayIcon2xPath),
+      template: toProjectRelative(trayTemplatePath),
+      templateRetina: toProjectRelative(trayTemplate2xPath),
+    },
+  };
+  await writeBuffer(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  return manifest;
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const manifest = await generateElectronIcons(parsed);
+  process.stdout.write(`${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+if (resolve(process.argv[1] ?? '') === SCRIPT_PATH) {
+  void main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/testing/check-platform-ingress.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Verify platform-owned browser ingress against a Cats base URL.
+ *
+ * Usage:
+ *   node scripts/testing/check-platform-ingress.mjs
+ *   node scripts/testing/check-platform-ingress.mjs --base-url http://192.168.1.25:8181
+ *   node scripts/testing/check-platform-ingress.mjs --base-url https://example.ts.net
+ */
+import process from 'node:process';
+
+const DEFAULT_BASE_URL = 'http://127.0.0.1:8181';
+
+function usage() {
+  return [
+    'Usage: node scripts/testing/check-platform-ingress.mjs [--base-url <url>]',
+    '',
+    'Checks:',
+    '  - GET /health',
+    '  - GET /api/platform/ingress',
+    '  - GET /runtime',
+    '  - GET /runtime/setup',
+    '  - GET /runtime/dashboard?bootstrap=1',
+    '  - GET /runtime/api/health',
+    '',
+    'Notes:',
+    '  - runtime API health accepts 200 or 503 so the proxy path can be verified',
+    '    without forcing a healthy upstream runtime.',
+  ].join('\n');
+}
+
+export function parseArgs(argv = process.argv.slice(2)) {
+  let baseUrl = DEFAULT_BASE_URL;
+  let help = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--help' || argument === '-h') {
+      help = true;
+      continue;
+    }
+    if (argument === '--base-url') {
+      const value = argv[index + 1];
+      if (!value) {
+        throw new Error('Missing value for --base-url');
+      }
+      baseUrl = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${argument}`);
+  }
+
+  return {
+    baseUrl,
+    help,
+  };
+}
+
+function normalizeBaseUrl(rawBaseUrl) {
+  const url = new URL(rawBaseUrl);
+  url.pathname = url.pathname.replace(/\/+$/u, '');
+  url.search = '';
+  url.hash = '';
+  const normalized = url.toString();
+  return normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+}
+
+function resolveUrl(baseUrl, pathname) {
+  return new URL(pathname, `${baseUrl}/`).toString();
+}
+
+function expectStatus(response, allowedStatuses, label) {
+  if (!allowedStatuses.includes(response.status)) {
+    throw new Error(`${label} returned HTTP ${response.status}`);
+  }
+}
+
+function expectContentType(response, pattern, label) {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!pattern.test(contentType)) {
+    throw new Error(`${label} returned unexpected content-type: ${contentType || '<empty>'}`);
+  }
+}
+
+function normalizeRuntimeRootPath(pathname) {
+  const normalized = pathname.trim() || '/runtime';
+  return normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+}
+
+function formatUrlSection(label, urls) {
+  if (!urls.length) {
+    return `${label}: none`;
+  }
+  return `${label}: ${urls.join(', ')}`;
+}
+
+export function formatPlatformIngressReport(result) {
+  const { baseUrl, ingress, checks } = result;
+  const lines = [
+    `Base URL: ${baseUrl}`,
+    `Binding: ${ingress.binding.mode} (${ingress.binding.host}:${ingress.binding.port})`,
+    `LAN reachable: ${ingress.binding.canReachFromLan ? 'yes' : 'no'}`,
+    formatUrlSection('Local URLs', ingress.urls.localUrls),
+    formatUrlSection('LAN URLs', ingress.urls.lanUrls),
+    formatUrlSection('Overlay URLs', ingress.urls.overlayUrls ?? []),
+    `Runtime ingress root: ${ingress.runtimeIngress.rootPath}`,
+    `Runtime ingress API: ${ingress.runtimeIngress.apiBasePath}`,
+    'Checks:',
+    ...checks.map((check) => {
+      const detail = check.location ? ` -> ${check.location}` : '';
+      return `- ${check.label}: HTTP ${check.status}${detail}`;
+    }),
+    'Notes:',
+    ...ingress.notes.map((note) => `- ${note}`),
+  ];
+  return lines.join('\n');
+}
+
+export async function probePlatformIngress(options = {}) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+
+  const ingressResponse = await fetchImpl(resolveUrl(baseUrl, '/api/platform/ingress'));
+  expectStatus(ingressResponse, [200], 'GET /api/platform/ingress');
+  expectContentType(ingressResponse, /application\/json/u, 'GET /api/platform/ingress');
+  const ingress = await ingressResponse.json();
+
+  const runtimeRootPath = normalizeRuntimeRootPath(ingress.runtimeIngress?.rootPath ?? '/runtime');
+  const runtimeApiBasePath = normalizeRuntimeRootPath(ingress.runtimeIngress?.apiBasePath ?? '/runtime/api');
+  const setupPath = `${runtimeRootPath}/setup`;
+  const dashboardBootstrapPath = `${runtimeRootPath}/dashboard?bootstrap=1`;
+  const runtimeHealthPath = `${runtimeApiBasePath}/health`;
+
+  const checks = [];
+
+  const healthResponse = await fetchImpl(resolveUrl(baseUrl, '/health'));
+  expectStatus(healthResponse, [200], 'GET /health');
+  checks.push({
+    label: 'GET /health',
+    status: healthResponse.status,
+  });
+
+  checks.push({
+    label: 'GET /api/platform/ingress',
+    status: ingressResponse.status,
+  });
+
+  const runtimeRootResponse = await fetchImpl(resolveUrl(baseUrl, runtimeRootPath));
+  expectStatus(runtimeRootResponse, [200], `GET ${runtimeRootPath}`);
+  expectContentType(runtimeRootResponse, /text\/html/u, `GET ${runtimeRootPath}`);
+  checks.push({
+    label: `GET ${runtimeRootPath}`,
+    status: runtimeRootResponse.status,
+  });
+
+  const runtimeSetupResponse = await fetchImpl(resolveUrl(baseUrl, setupPath));
+  expectStatus(runtimeSetupResponse, [200], `GET ${setupPath}`);
+  expectContentType(runtimeSetupResponse, /text\/html/u, `GET ${setupPath}`);
+  checks.push({
+    label: `GET ${setupPath}`,
+    status: runtimeSetupResponse.status,
+  });
+
+  const runtimeDashboardResponse = await fetchImpl(resolveUrl(baseUrl, dashboardBootstrapPath), {
+    redirect: 'manual',
+  });
+  expectStatus(runtimeDashboardResponse, [200, 302], `GET ${dashboardBootstrapPath}`);
+  const runtimeDashboardLocation = runtimeDashboardResponse.headers.get('location');
+  if (runtimeDashboardResponse.status === 302) {
+    if (runtimeDashboardLocation !== setupPath) {
+      throw new Error(
+        `GET ${dashboardBootstrapPath} redirected to unexpected location: ${runtimeDashboardLocation ?? '<empty>'}`,
+      );
+    }
+  }
+  checks.push({
+    label: `GET ${dashboardBootstrapPath}`,
+    status: runtimeDashboardResponse.status,
+    location: runtimeDashboardLocation ?? '',
+  });
+
+  const runtimeHealthResponse = await fetchImpl(resolveUrl(baseUrl, runtimeHealthPath));
+  expectStatus(runtimeHealthResponse, [200, 503], `GET ${runtimeHealthPath}`);
+  expectContentType(runtimeHealthResponse, /application\/json/u, `GET ${runtimeHealthPath}`);
+  checks.push({
+    label: `GET ${runtimeHealthPath}`,
+    status: runtimeHealthResponse.status,
+  });
+
+  return {
+    baseUrl,
+    ingress,
+    checks,
+  };
+}
+
+export async function runPlatformIngressSmoke(argv = process.argv.slice(2), options = {}) {
+  const stdout = options.stdout ?? process.stdout;
+  const { baseUrl, help } = parseArgs(argv);
+
+  if (help) {
+    stdout.write(`${usage()}\n`);
+    return null;
+  }
+
+  const result = await probePlatformIngress({
+    baseUrl,
+    fetchImpl: options.fetchImpl,
+  });
+  stdout.write(`${formatPlatformIngressReport(result)}\n`);
+  return result;
+}
+
+function isDirectExecution(metaUrl) {
+  const entry = process.argv[1];
+  if (!entry) {
+    return false;
+  }
+  return new URL(`file://${entry.replace(/\\/gu, '/')}`).href === metaUrl;
+}
+
+if (isDirectExecution(import.meta.url)) {
+  try {
+    await runPlatformIngressSmoke();
+  } catch (error) {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exitCode = 1;
+  }
+}

package/scripts/windows/Build-DesktopPackage.ps1

@@ -0,0 +1,47 @@
+<#
+.SYNOPSIS
+    Build staged desktop packaging outputs for Cats.
+
+.DESCRIPTION
+    Runs the cross-platform desktop packaging script for the requested target
+    platform and writes staged artifacts plus installer manifests under the
+    configured packaging output directory.
+
+.PARAMETER Platform
+    Target platform filter: all, windows, macos, or linux.
+
+.PARAMETER OutputDir
+    Optional override for the packaging output directory.
+
+.EXAMPLE
+    .\scripts\windows\Build-DesktopPackage.ps1 -Platform windows
+    Build the staged Windows packaging outputs.
+#>
+param(
+  [ValidateSet('all', 'windows', 'macos', 'linux')]
+  [string]$Platform = 'all',
+  [string]$OutputDir = ''
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$projectRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
+
+Push-Location $projectRoot
+try {
+  npm run build | Out-Host
+  if ($LASTEXITCODE -ne 0) {
+    throw "npm run build failed with exit code $LASTEXITCODE"
+  }
+  if ($OutputDir) {
+    node .\scripts\package-desktop.mjs --platform $Platform --output-dir $OutputDir
+  } else {
+    node .\scripts\package-desktop.mjs --platform $Platform
+  }
+  if ($LASTEXITCODE -ne 0) {
+    throw "desktop packaging failed with exit code $LASTEXITCODE"
+  }
+} finally {
+  Pop-Location
+}

package/scripts/windows/Build-WindowsInstaller.ps1

@@ -0,0 +1,29 @@
+<#
+.SYNOPSIS
+    Build a Windows NSIS installer for Cats.
+
+.DESCRIPTION
+    Builds cats-runtime, builds Cats, stages bundled sidecar assets, and runs
+    electron-builder with the NSIS target so the result can be installed and
+    tested on Windows.
+
+.EXAMPLE
+    .\scripts\windows\Build-WindowsInstaller.ps1
+    Build the Windows NSIS installer into cats/release/.
+#>
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$projectRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
+
+Push-Location $projectRoot
+try {
+  node .\scripts\build-desktop-installer.mjs --target windows
+  if ($LASTEXITCODE -ne 0) {
+    throw "desktop installer build failed with exit code $LASTEXITCODE"
+  }
+} finally {
+  Pop-Location
+}