@cats-inc/cats-platform 0.1.21 → 0.3.4

package/scripts/build-desktop-installer.mjs

@@ -8,6 +8,7 @@ import { spawn } from 'node:child_process';
 
 import { parseStableReleaseTag } from './validate-release-version.mjs';
 import { DESCRIPTOR_RELATIVE_PATH } from './generate-desktop-release-descriptor.mjs';
+import { resolveAppLock, materializeAppSelection } from '#cats-app-package';
 
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
@@ -32,11 +33,13 @@ Options:
   --format <nsis|dmg|pkg|zip|AppImage|deb|tar.gz>
                                          Override the configured installer formats.
   --sidecar-layout <split|bundle>         Choose loose-file or bundled sidecars for both app/runtime.
+  --apps-lock <path>                      Bundle the exact ID/version/SHA-256 selection in this lock.
   --skip-mobile                           Skip the mobile bundle (\`expo export\`). Also honored via
                                           CATS_SKIP_MOBILE=1 in the environment or .env.
   --release                               Build an official release package: embed the release
-                                          descriptor, require platform signing credentials, and
-                                          allow signing identity discovery. Requires a GitHub
+                                          descriptor, require platform signing credentials (plus
+                                          macOS notarization credentials), and allow signing
+                                          identity discovery. Requires a GitHub
                                           Actions tag run whose tag matches the package version.
                                           Also honored via CATS_DESKTOP_RELEASE_MODE=1.
   --preview                               Build an unsupported unsigned GitHub prerelease preview.
@@ -44,6 +47,12 @@ Options:
                                           omits the official descriptor, and disables signing
                                           identity discovery. Also honored via
                                           CATS_DESKTOP_PREVIEW_MODE=1.
+  --sign                                  Let local packaging use a signing identity from the
+                                          OS keychain. Off by default so an unconfigured machine
+                                          cannot pick up an unrelated certificate. Ignored by
+                                          --release and --preview, which always sign when their
+                                          credentials are present. Also honored via
+                                          CATS_DESKTOP_SIGN_LOCAL=1.
   --publish <never|always>                Publish policy, default never. Publishing requires
                                           --release or --preview plus a GitHub token. Also honored
                                           via CATS_DESKTOP_PUBLISH.
@@ -97,11 +106,13 @@ export function parseArgs(argv, env = process.env) {
   let skipMobile = parseBooleanFlag(env.CATS_SKIP_MOBILE);
   let releaseMode = parseBooleanFlag(env.CATS_DESKTOP_RELEASE_MODE);
   let previewMode = parseBooleanFlag(env.CATS_DESKTOP_PREVIEW_MODE);
+  let allowLocalSigning = parseBooleanFlag(env.CATS_DESKTOP_SIGN_LOCAL);
   let publish = resolvePublishPolicy(env.CATS_DESKTOP_PUBLISH);
   // GITHUB_REF_NAME is a runner-provided default. A workflow `env:` block
   // cannot override anything in the GITHUB_ namespace, and a preview run is
   // dispatched from a branch, so the tag has to arrive as an explicit input.
   let tag = (env.CATS_DESKTOP_RELEASE_TAG ?? env.GITHUB_REF_NAME ?? '').trim();
+  let appsLock = env.CATS_DESKTOP_APPS_LOCK?.trim() || null;
 
   for (let index = 0; index < argv.length; index += 1) {
     const value = argv[index];
@@ -115,14 +126,21 @@ export function parseArgs(argv, env = process.env) {
         skipMobile,
         releaseMode,
         previewMode,
+        allowLocalSigning,
         publish,
         tag,
+        ...(appsLock ? { appsLock } : {}),
       };
     }
     if (value === '--release') {
       releaseMode = true;
       continue;
     }
+    if (value === '--apps-lock') {
+      appsLock = argv[++index];
+      if (!appsLock || appsLock.startsWith('--')) throw new Error('--apps-lock requires a path.');
+      continue;
+    }
     if (value === '--no-release') {
       releaseMode = false;
       continue;
@@ -135,6 +153,14 @@ export function parseArgs(argv, env = process.env) {
       previewMode = false;
       continue;
     }
+    if (value === '--sign') {
+      allowLocalSigning = true;
+      continue;
+    }
+    if (value === '--no-sign') {
+      allowLocalSigning = false;
+      continue;
+    }
     if (value === '--publish') {
       publish = resolvePublishPolicy(argv[index + 1] ?? '');
       index += 1;
@@ -185,8 +211,10 @@ export function parseArgs(argv, env = process.env) {
     skipMobile,
     releaseMode,
     previewMode,
+    allowLocalSigning,
     publish,
     tag,
+    ...(appsLock ? { appsLock } : {}),
   };
 }
 
@@ -231,28 +259,45 @@ async function resolveCommandInvocation(command, args) {
   };
 }
 
+const MACOS_NOTARIZATION_CREDENTIAL_KEYS = [
+  'APPLE_API_KEY',
+  'APPLE_API_KEY_ID',
+  'APPLE_API_ISSUER',
+];
+
 const SIGNING_CREDENTIAL_KEYS = [
   'WIN_CSC_LINK',
   'CSC_LINK',
   'WIN_CSC_KEY_PASSWORD',
   'CSC_KEY_PASSWORD',
+  ...MACOS_NOTARIZATION_CREDENTIAL_KEYS,
 ];
 
 /**
  * Local and test packaging must never reach for a signing identity, because an
  * unconfigured machine would otherwise pick up an unrelated certificate from
- * the OS keychain. Release mode leaves identity discovery to the workflow so a
- * configured certificate can actually be used.
+ * the OS keychain. Both guarded workflow paths leave identity discovery alone
+ * so a configured certificate can actually be used.
+ *
+ * ADR-117: a preview is signed on any platform whose credentials exist, so
+ * preview mode is a signing path too. Signing is artifact trust; it says
+ * nothing about whether the build claims official release identity.
  *
- * Empty credential variables are dropped in both modes: electron-builder treats
+ * `--sign` is the local escape hatch. It is an explicit request rather than an
+ * inference from the environment, because a developer machine may hold
+ * unrelated certificates.
+ *
+ * Empty credential variables are dropped in every mode: electron-builder treats
  * an empty CSC_LINK as a relative path and resolves it against the project
  * root.
  */
 export function buildInstallerEnvironment(baseEnv = process.env, options = {}) {
-  const releaseMode = options.releaseMode === true;
+  const signingAllowed = options.releaseMode === true
+    || options.previewMode === true
+    || options.allowLocalSigning === true;
   const env = { ...baseEnv };
 
-  if (!releaseMode) {
+  if (!signingAllowed) {
     env.CSC_IDENTITY_AUTO_DISCOVERY = 'false';
   }
 
@@ -276,6 +321,22 @@ export function hasMacosSigningCredentials(env = process.env) {
   return typeof link === 'string' && link.trim() !== '';
 }
 
+/**
+ * electron-builder reads notarization credentials straight from the
+ * environment and only warns when they are absent, so a misconfigured release
+ * would otherwise produce a signed but un-notarized app. Gatekeeper rejects
+ * that on every machine except the one that built it.
+ *
+ * App Store Connect API keys are used rather than an Apple ID and
+ * app-specific password: they are revocable on their own and survive an Apple
+ * ID password change, which a CI secret has no way to notice.
+ */
+export function hasMacosNotarizationCredentials(env = process.env) {
+  return MACOS_NOTARIZATION_CREDENTIAL_KEYS.every(
+    (key) => typeof env[key] === 'string' && env[key].trim() !== '',
+  );
+}
+
 /**
  * Signing is a release gate, not a nice-to-have.
  *
@@ -292,16 +353,53 @@ export function resolveSigningProblems({ env = process.env, target } = {}) {
     }];
   }
 
-  if (target === 'macos' && !hasMacosSigningCredentials(env)) {
-    return [{
-      code: 'release_macos_signing_missing',
-      message: 'An official macOS release requires CSC_LINK.',
-    }];
+  if (target === 'macos') {
+    const problems = [];
+    if (!hasMacosSigningCredentials(env)) {
+      problems.push({
+        code: 'release_macos_signing_missing',
+        message: 'An official macOS release requires CSC_LINK.',
+      });
+    }
+    if (!hasMacosNotarizationCredentials(env)) {
+      problems.push({
+        code: 'release_macos_notarization_missing',
+        message: 'An official macOS release requires APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER.',
+      });
+    }
+    return problems;
   }
 
   return [];
 }
 
+/**
+ * ADR-117: trust is resolved per platform from the credentials actually
+ * present. The build states which it got, because a silently unsigned artifact
+ * is indistinguishable from a signed one until a user tries to install it.
+ */
+export function describeArtifactTrust(target, env = process.env) {
+  if (target === 'linux') {
+    return 'unsigned (Linux packages are not signed)';
+  }
+
+  if (target === 'windows') {
+    return hasWindowsSigningCredentials(env)
+      ? 'signed'
+      : 'unsigned (no Windows certificate configured)';
+  }
+
+  const signed = hasMacosSigningCredentials(env);
+  const notarized = hasMacosNotarizationCredentials(env);
+  if (signed && notarized) {
+    return 'signed and notarized';
+  }
+  if (signed) {
+    return 'signed but NOT notarized (no App Store Connect API key) — Gatekeeper will reject the download';
+  }
+  return 'unsigned (no Developer ID certificate)';
+}
+
 /**
  * Release and preview publication are only meaningful inside the guarded
  * workflow. Anything else could publish from an unreviewed tree, so the
@@ -638,8 +736,14 @@ export function electronBuilderArgs(target, archOverride, formatOverride, option
   }
 
   const releaseMode = options.releaseMode === true;
+  const previewMode = options.previewMode === true;
+  // Signing overrides key off artifact trust, not release identity, so both
+  // guarded paths qualify. Local packaging never does, even with `--sign`:
+  // an ad-hoc local build has no reason to reach Apple's notary service.
+  const signedBuild = releaseMode || previewMode;
   const publish = resolvePublishPolicy(options.publish ?? 'never');
   const signWindowsExecutable = options.signWindowsExecutable === true;
+  const notarizeMacos = options.notarizeMacos === true;
   const formats = normalizeFormats(target, formatOverride);
   const platformFlag = target === 'windows' ? '--win' : target === 'macos' ? '--mac' : '--linux';
   const args = ['electron-builder', platformFlag];
@@ -657,10 +761,17 @@ export function electronBuilderArgs(target, archOverride, formatOverride, option
   // package.json pins signAndEditExecutable to false so unsigned local builds
   // avoid the winCodeSign download. A release build with real credentials has
   // to opt back in, and only then.
-  if (releaseMode && target === 'windows' && signWindowsExecutable) {
+  if (signedBuild && target === 'windows' && signWindowsExecutable) {
     args.push('-c.win.signAndEditExecutable=true');
   }
 
+  // package.json pins mac.notarize to false so an unsigned preview never waits
+  // on Apple and a half-configured environment cannot quietly ship an
+  // un-notarized build. A release build with real credentials opts back in.
+  if (signedBuild && target === 'macos' && notarizeMacos) {
+    args.push('-c.mac.notarize=true');
+  }
+
   args.push('--publish', publish);
   return args;
 }
@@ -673,7 +784,15 @@ async function main() {
   }
 
   const resolvedTarget = resolveBuilderTarget(parsed.target);
-  const envOptions = { releaseMode: parsed.releaseMode };
+  // Resolve once before builds can clear build/. Stage an offline immutable copy
+  // in an OS temporary directory so retries never redownload a moving asset.
+  const selectedApps = parsed.appsLock ? await resolveAppLock(resolve(parsed.appsLock)) : null;
+  const appLockForBuild = selectedApps ? await materializeAppSelection(selectedApps) : null;
+  const envOptions = {
+    releaseMode: parsed.releaseMode,
+    previewMode: parsed.previewMode,
+    allowLocalSigning: parsed.allowLocalSigning,
+  };
 
   if (parsed.releaseMode && parsed.previewMode) {
     throw new Error('--release and --preview are mutually exclusive build modes.');
@@ -703,10 +822,11 @@ async function main() {
           .join('\n')}`,
       );
     }
-    const buildKind = parsed.releaseMode ? 'official' : 'unsigned preview';
+    const buildKind = parsed.releaseMode ? 'official' : 'preview';
     process.stdout.write(
       `[build-desktop-installer] ${buildKind} ${resolvedTarget} build for `
-        + `${process.env.GITHUB_REF_NAME} (publish=${parsed.publish}).\n`,
+        + `${process.env.GITHUB_REF_NAME} (publish=${parsed.publish}, `
+        + `trust=${describeArtifactTrust(resolvedTarget, process.env)}).\n`,
     );
   }
 
@@ -762,6 +882,7 @@ async function main() {
       resolvedTarget,
       '--sidecar-layout',
       parsed.sidecarLayout,
+      ...(appLockForBuild ? ['--apps-lock', appLockForBuild] : []),
     ],
     PROJECT_ROOT,
     sidecarBuildEnv,
@@ -771,8 +892,10 @@ async function main() {
     'npx',
     electronBuilderArgs(resolvedTarget, parsed.arch, parsed.format, {
       releaseMode: parsed.releaseMode,
+      previewMode: parsed.previewMode,
       publish: parsed.publish,
       signWindowsExecutable: hasWindowsSigningCredentials(process.env),
+      notarizeMacos: hasMacosNotarizationCredentials(process.env),
     }),
     PROJECT_ROOT,
     {},

package/scripts/build-test-ui.mjs

@@ -28,7 +28,7 @@ if (entryPoints.length === 0) {
 await build({
   entryPoints,
   bundle: true,
-  external: ['jsdom', 'typescript'],
+  external: ['jsdom', 'typescript', '#cats-app-package'],
   platform: 'node',
   format: 'esm',
   outbase: testsDir,

package/scripts/bundle-server.mjs

@@ -4,13 +4,26 @@ import { fileURLToPath } from 'node:url';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-await build({
-  entryPoints: [resolve(root, 'build', 'server', 'index.js')],
-  bundle: true,
-  outfile: resolve(root, 'build', 'server-bundle', 'index.js'),
-  platform: 'node',
-  target: 'node22',
-  format: 'esm',
-  sourcemap: true,
-  packages: 'external',
-});
+export function bundleServer({
+  entryPoint = resolve(root, 'build', 'server', 'index.js'),
+  outfile = resolve(root, 'build', 'server-bundle', 'index.js'),
+} = {}) {
+  return build({
+    entryPoints: [entryPoint],
+    bundle: true,
+    outfile,
+    platform: 'node',
+    target: 'node22',
+    format: 'esm',
+    sourcemap: true,
+    packages: 'external',
+    // Package-import aliases are otherwise inlined despite packages: external.
+    // Keep the SDK's import.meta.url beside its shipped browser.js resource.
+    external: ['#cats-app-package'],
+  });
+}
+
+if (resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--help')) console.log('Usage: node scripts/bundle-server.mjs (after npm run build:server)');
+  else await bundleServer();
+}

package/scripts/linux/build-desktop-package.sh

@@ -3,7 +3,7 @@
 # Script: build-desktop-package.sh
 # Description: Build staged desktop packaging outputs for Cats.
 #
-# Usage: ./scripts/linux/build-desktop-package.sh [all|windows|macos|linux] [output-dir]
+# Usage: ./scripts/linux/build-desktop-package.sh [all|windows|macos|linux] [output-dir] [apps-lock]
 #
 # Arguments:
 #   [platform]    Optional platform filter. Defaults to all.
@@ -20,11 +20,11 @@ SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd)"
 PLATFORM="${1:-all}"
 OUTPUT_DIR="${2:-}"
+APPS_LOCK="${3:-}"
 
 cd "${PROJECT_ROOT}"
 npm run build
-if [[ -n "${OUTPUT_DIR}" ]]; then
-  node ./scripts/package-desktop.mjs --platform "${PLATFORM}" --output-dir "${OUTPUT_DIR}"
-else
-  node ./scripts/package-desktop.mjs --platform "${PLATFORM}"
-fi
+package_args=(./scripts/package-desktop.mjs --platform "${PLATFORM}")
+if [[ -n "${OUTPUT_DIR}" ]]; then package_args+=(--output-dir "${OUTPUT_DIR}"); fi
+if [[ -n "${APPS_LOCK}" ]]; then package_args+=(--apps-lock "${APPS_LOCK}"); fi
+node "${package_args[@]}"

package/scripts/linux/install-github-cli.sh

@@ -60,6 +60,11 @@ declare -a applied_changes=()
 declare -a warnings=()
 declare -a manual_steps=()
 
+# A Desktop-launched helper may inherit PATH from before gh was installed.
+# Include our fallback destination and the supported Homebrew locations in this
+# process only; check mode must not edit the user's shell profile.
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+
 resolve_gh_path() {
   command -v gh 2>/dev/null || true
 }

package/scripts/linux/install-meta-cli.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=provider-cli-common.sh
+source "$SCRIPT_DIR/provider-cli-common.sh"
+
+run_native_provider_installer 'linux' 'muse' "$@"

package/scripts/linux/install-node.sh

@@ -90,7 +90,7 @@ is_node_installed() {
   if [ "$skip_node_probe" = 'true' ]; then
     return 1
   fi
-  command -v node >/dev/null 2>&1
+  command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1
 }
 
 json_array_from_lines() {
@@ -149,6 +149,12 @@ JSON
   exit "$exit_code"
 }
 
+# Desktop's environment may predate nvm installation. Load it before read-only
+# detection too; a bundled or standalone node without npm is not this substrate.
+if [ "$install_state" = 'auto' ] && [ "$skip_node_probe" = 'false' ]; then
+  load_nvm
+fi
+
 # Mode: check
 if [ "$mode" = 'check' ]; then
   if is_node_installed; then
@@ -214,10 +220,10 @@ case "$mode" in
     ;;
 esac
 
-if command -v node >/dev/null 2>&1; then
+if command -v node >/dev/null 2>&1 && command -v npm >/dev/null 2>&1; then
   emit_result 'ready' 'true' 0
 else
-  warnings+=('Node binary still missing after install.')
+  warnings+=('Node.js or npm is still missing after install.')
   manual_steps+=('Open a new terminal so PATH picks up the nvm-managed node binary.')
   emit_result 'failed' 'false' 1
 fi