@cats-inc/cats-platform 0.1.0

package/scripts/macos/sync-agent-skills.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+clean=false
+agent=""
+
+print_usage() {
+  cat <<'EOF'
+Usage: sync-agent-skills.sh [--clean] [--agent claude|codex]
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --clean)
+      clean=true
+      shift
+      ;;
+    --agent)
+      shift
+      if [[ $# -eq 0 ]]; then
+        echo "--agent requires a value" >&2
+        exit 1
+      fi
+      case "$1" in
+        claude|codex)
+          agent="$1"
+          ;;
+        *)
+          echo "Unsupported agent: $1" >&2
+          exit 1
+          ;;
+      esac
+      shift
+      ;;
+    -h|--help)
+      print_usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      print_usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+project_root="$(cd "${script_dir}/../.." && pwd)"
+while [[ "$project_root" != "/" && ! -f "$project_root/AGENTS.md" ]]; do
+  project_root="$(dirname "$project_root")"
+done
+
+if [[ ! -f "$project_root/AGENTS.md" ]]; then
+  echo "Could not find project root (no AGENTS.md found)." >&2
+  exit 1
+fi
+
+skills_dir="$project_root/skills"
+if [[ ! -d "$skills_dir" ]]; then
+  echo "No skills/ directory found at $skills_dir" >&2
+  exit 0
+fi
+
+resolve_target_dir() {
+  case "$1" in
+    claude) echo "$project_root/.claude/skills" ;;
+    codex) echo "$project_root/.agents/skills" ;;
+    *) return 1 ;;
+  esac
+}
+
+agents=(claude codex)
+if [[ -n "$agent" ]]; then
+  agents=("$agent")
+fi
+
+skill_dirs=()
+for entry in "$skills_dir"/*; do
+  [[ -d "$entry" ]] || continue
+  [[ -f "$entry/SKILL.md" ]] || continue
+  skill_dirs+=("$entry")
+done
+
+if [[ ${#skill_dirs[@]} -eq 0 ]]; then
+  echo "No skills found in $skills_dir (no directories with SKILL.md)" >&2
+  exit 0
+fi
+
+for agent_name in "${agents[@]}"; do
+  target_dir="$(resolve_target_dir "$agent_name")"
+  if [[ "$clean" == true && -d "$target_dir" ]]; then
+    rm -rf "$target_dir"
+  fi
+  mkdir -p "$target_dir"
+  for skill_dir in "${skill_dirs[@]}"; do
+    skill_name="$(basename "$skill_dir")"
+    rm -rf "$target_dir/$skill_name"
+    cp -R "$skill_dir" "$target_dir/"
+  done
+  printf 'Synced %s skill(s) to %s: %s\n' "${#skill_dirs[@]}" "$agent_name" "$target_dir"
+done

package/scripts/macos/test-macos-package-smoke.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+#
+# Script: test-macos-package-smoke.sh
+# Description: Validate an unpacked macOS Cats desktop package.
+#
+# Usage: ./scripts/macos/test-macos-package-smoke.sh [app-root]
+#
+
+set -euo pipefail
+
+APP_ROOT="${1:-release/mac-universal/Cats.app}"
+RESOURCES_ROOT="${APP_ROOT}/Contents/Resources"
+PLAN_PATH="${RESOURCES_ROOT}/desktop-package-plan.json"
+
+log() {
+  printf '[smoke] %s\n' "$1"
+}
+
+pass() {
+  printf '[pass] %s\n' "$1"
+}
+
+assert_file() {
+  local path="$1"
+  local label="$2"
+  if [[ ! -f "${path}" ]]; then
+    printf 'Missing %s at %s\n' "${label}" "${path}" >&2
+    exit 1
+  fi
+  pass "${label} found at ${path}"
+}
+
+log "Validating macOS app bundle under ${APP_ROOT}"
+
+assert_file "${RESOURCES_ROOT}/app-sidecar/build/server/index.js" 'bundled cats server entry'
+assert_file "${RESOURCES_ROOT}/app-sidecar/build/renderer/index.html" 'bundled cats renderer build'
+assert_file "${RESOURCES_ROOT}/app-sidecar/package.json" 'bundled cats app package manifest'
+assert_file "${RESOURCES_ROOT}/app-sidecar/node_modules/js-yaml/package.json" 'bundled cats app js-yaml dependency marker'
+assert_file "${RESOURCES_ROOT}/app-sidecar/node_modules/argparse/package.json" 'bundled cats app argparse dependency marker'
+assert_file "${RESOURCES_ROOT}/cats-runtime/build/runtime/index.js" 'bundled cats-runtime entry'
+assert_file "${RESOURCES_ROOT}/cats-runtime/package.json" 'bundled cats-runtime package manifest'
+assert_file "${RESOURCES_ROOT}/cats-runtime/public/provider-setup.html" 'bundled cats-runtime setup UI'
+assert_file "${RESOURCES_ROOT}/cats-runtime/skills/README.md" 'bundled cats-runtime skills catalog root'
+assert_file "${RESOURCES_ROOT}/cats-runtime/config/management.yaml.example" 'bundled cats-runtime management config example'
+assert_file "${RESOURCES_ROOT}/cats-runtime/config/providers.yaml.example" 'bundled cats-runtime provider config example'
+assert_file "${RESOURCES_ROOT}/cats-runtime/config/curated-model-catalogs.yaml.example" 'bundled cats-runtime curated model catalog example'
+assert_file "${RESOURCES_ROOT}/cats-runtime/node_modules/playwright-core/package.json" 'bundled cats-runtime external dependency marker'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-node.sh" 'bundled macOS Node.js LTS host installer'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-github-cli.sh" 'bundled macOS GitHub CLI host installer'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/setup-node-global-prefix.sh" 'bundled macOS npm prefix helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-codex.sh" 'bundled macOS OpenAI Codex installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-antigravity.sh" 'bundled macOS Antigravity installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-copilot.sh" 'bundled macOS GitHub Copilot installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-opencode.sh" 'bundled macOS OpenCode installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-kilo.sh" 'bundled macOS Kilo Code installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-auggie.sh" 'bundled macOS Auggie installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-pi.sh" 'bundled macOS Pi installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-claude-code.sh" 'bundled macOS Claude Code installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-cursor-agent.sh" 'bundled macOS Cursor Agent installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-goose.sh" 'bundled macOS Goose installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-junie.sh" 'bundled macOS Junie installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/install-kiro-cli.sh" 'bundled macOS Kiro installer helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/check-installation.sh" 'bundled macOS readiness audit helper'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/provider-cli-common.sh" 'bundled macOS provider helper library'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/macos/node-cli-common.sh" 'bundled macOS npm helper library'
+assert_file "${RESOURCES_ROOT}/desktop/setup-assets/manifest.json" 'bundled setup-assets manifest'
+assert_file "${PLAN_PATH}" 'bundled desktop packaging plan'
+
+node - <<'NODE' "${PLAN_PATH}"
+const fs = require('node:fs');
+
+const [planPath] = process.argv.slice(2);
+const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'));
+const macTarget = Array.isArray(plan.targets)
+  ? plan.targets.find((target) => target.platform === 'macos')
+  : null;
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+assert(plan.strategy === 'electron-sidecar-bundle', 'installer packaging strategy is electron-sidecar-bundle');
+assert(plan.selfHostedNpmCompatible === true, 'installer keeps self-hosted npm compatibility');
+assert(Boolean(macTarget), 'installer packaging plan includes a macOS target');
+assert(macTarget.installerFormats.includes('dmg'), 'macOS target includes dmg packaging');
+assert(macTarget.installerFormats.includes('pkg'), 'macOS target includes pkg packaging');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-opencode-native-installer-script'), 'macOS target includes the bundled OpenCode installer asset');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-codex-native-installer-script'), 'macOS target includes the bundled OpenAI Codex installer asset');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-antigravity-native-installer-script'), 'macOS target includes the bundled Antigravity installer asset');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-setup-readiness-audit-script'), 'macOS target includes the bundled readiness audit asset');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-provider-cli-common-support-script'), 'macOS target includes the macOS provider helper asset');
+assert(macTarget.artifacts.some((artifact) => artifact.id === 'macos-node-cli-common-support-script'), 'macOS target includes the macOS npm helper asset');
+assert(plan.installer.providerSetup.localProviders.some((provider) => provider.id === 'kiro' && provider.platform === 'macos'), 'installer contract keeps Kiro in the macOS bundled local-provider rollout');
+assert(plan.installer.providerSetup.helperCatalog.some((helper) => helper.id === 'macos-install-readiness-audit'), 'installer contract includes macOS readiness helper metadata');
+assert(!plan.installer.providerSetup.helperCatalog.some((helper) => helper.id === 'windows-install-readiness-audit'), 'installer contract omits Windows-only helper metadata from the macOS package');
+NODE
+
+pass 'macOS unpacked package smoke-check completed successfully'

package/scripts/macos/upgrade-cli-tools.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+print_usage() {
+  cat <<'EOF'
+Usage: upgrade-cli-tools.sh [--skip-node] [--help]
+
+Repo-owned self-hosted bulk upgrade helper for the Unix provider baseline.
+
+Options:
+  --skip-node  Skip the npm CLI pack upgrade pass.
+  --help       Show this help text.
+EOF
+}
+
+skip_node='false'
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --skip-node)
+      skip_node='true'
+      ;;
+    -h|--help)
+      print_usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown option: %s\n' "$1" >&2
+      print_usage >&2
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+for script_name in install-claude-code.sh install-antigravity.sh install-cursor-agent.sh install-goose.sh install-junie.sh install-kiro-cli.sh; do
+  "$SCRIPT_DIR/$script_name" -Upgrade
+done
+
+if [ "$skip_node" = 'false' ]; then
+  for script_name in install-codex.sh install-copilot.sh install-opencode.sh install-kilo.sh install-auggie.sh install-pi.sh; do
+    "$SCRIPT_DIR/$script_name" -upgrade
+  done
+fi

package/scripts/package-desktop.mjs

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { access, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const DESKTOP_ICON_MANIFEST_RELATIVE_PATH = 'assets/build/icon-manifest.json';
+const REQUIRED_DESKTOP_ICON_RELATIVE_PATHS = [
+  'assets/build/icon.png',
+  'assets/build/icon.ico',
+  'assets/build/icon.icns',
+  'assets/build/installerIcon.ico',
+  'assets/build/uninstallerIcon.ico',
+  'assets/build/installerHeaderIcon.ico',
+  'assets/build/icons/linux/16x16.png',
+  'assets/build/icons/linux/24x24.png',
+  'assets/build/icons/linux/32x32.png',
+  'assets/build/icons/linux/48x48.png',
+  'assets/build/icons/linux/64x64.png',
+  'assets/build/icons/linux/128x128.png',
+  'assets/build/icons/linux/256x256.png',
+  'assets/build/icons/linux/512x512.png',
+  'assets/tray-icon.png',
+  'assets/tray-icon@2x.png',
+  'assets/tray-iconTemplate.png',
+  'assets/tray-iconTemplate@2x.png',
+];
+
+function printHelp() {
+  process.stdout.write(`Usage: node scripts/package-desktop.mjs [options]
+
+Options:
+  --platform <all|windows|macos|linux>  Filter staged target manifests
+  --output-dir <path>                   Override packaging output root
+  --sidecar-layout <split|bundle>       Choose loose-file or bundled sidecars for both app/runtime
+  --help                                Show this help text
+`);
+}
+
+function resolveSidecarLayout(value) {
+  if (value === undefined || value === null || value === '') {
+    return 'split';
+  }
+  if (value === 'split' || value === 'bundle') {
+    return value;
+  }
+  throw new Error(`Unsupported sidecar layout: ${value}`);
+}
+
+export function parseArgs(argv, env = process.env) {
+  let platform = 'all';
+  let outputDir = null;
+  let sidecarLayout = resolveSidecarLayout(env.CATS_DESKTOP_SIDECAR_LAYOUT);
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--help' || value === '-h') {
+      return { help: true, platform, outputDir, sidecarLayout };
+    }
+    if (value === '--platform') {
+      platform = argv[index + 1] ?? 'all';
+      index += 1;
+      continue;
+    }
+    if (value === '--output-dir') {
+      outputDir = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (value === '--sidecar-layout') {
+      sidecarLayout = resolveSidecarLayout(argv[index + 1] ?? '');
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${value}`);
+  }
+
+  return { help: false, platform, outputDir, sidecarLayout };
+}
+
+export function resolveRequiredDesktopIconPaths(projectRoot = PROJECT_ROOT) {
+  return [
+    ...REQUIRED_DESKTOP_ICON_RELATIVE_PATHS,
+    DESKTOP_ICON_MANIFEST_RELATIVE_PATH,
+  ].map((relativePath) => resolve(projectRoot, relativePath));
+}
+
+function listDesktopIconManifestAssetPaths(manifest) {
+  return [
+    manifest?.app?.png,
+    manifest?.app?.ico,
+    manifest?.app?.icns,
+    manifest?.app?.installerIcon,
+    manifest?.app?.uninstallerIcon,
+    manifest?.app?.installerHeaderIcon,
+    ...Object.values(manifest?.app?.linuxIcons ?? {}),
+    manifest?.tray?.default,
+    manifest?.tray?.retina,
+    manifest?.tray?.template,
+    manifest?.tray?.templateRetina,
+  ].filter((value) => typeof value === 'string' && value.length > 0);
+}
+
+async function readDesktopIconManifest(projectRoot = PROJECT_ROOT) {
+  const manifestPath = resolve(projectRoot, DESKTOP_ICON_MANIFEST_RELATIVE_PATH);
+  try {
+    return JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(
+      `Invalid desktop icon manifest: ${DESKTOP_ICON_MANIFEST_RELATIVE_PATH}. ${
+        error instanceof Error ? error.message : 'Unable to parse manifest.'
+      }`,
+    );
+  }
+}
+
+async function assertDesktopIconManifestMatchesRequiredAssets(projectRoot = PROJECT_ROOT) {
+  const manifest = await readDesktopIconManifest(projectRoot);
+  const manifestPaths = listDesktopIconManifestAssetPaths(manifest);
+  const manifestPathSet = new Set(manifestPaths);
+  const requiredPathSet = new Set(REQUIRED_DESKTOP_ICON_RELATIVE_PATHS);
+  const missingFromManifest = REQUIRED_DESKTOP_ICON_RELATIVE_PATHS
+    .filter((relativePath) => !manifestPathSet.has(relativePath));
+  if (missingFromManifest.length > 0) {
+    throw new Error(
+      `Desktop icon manifest is missing generated asset: ${missingFromManifest[0]}. `
+      + 'Run `npm run desktop:icons` before packaging.',
+    );
+  }
+
+  const unexpectedManifestPath = manifestPaths.find((relativePath) =>
+    !requiredPathSet.has(relativePath));
+  if (unexpectedManifestPath) {
+    throw new Error(
+      `Desktop icon manifest references unexpected asset: ${unexpectedManifestPath}. `
+      + 'Run `npm run desktop:icons` before packaging.',
+    );
+  }
+}
+
+export async function assertDesktopIconAssetsPresent(projectRoot = PROJECT_ROOT) {
+  const requiredPaths = resolveRequiredDesktopIconPaths(projectRoot);
+  for (let index = 0; index < requiredPaths.length; index += 1) {
+    const absolutePath = requiredPaths[index];
+    try {
+      await access(absolutePath);
+    } catch {
+      throw new Error(
+        `Missing required desktop icon asset: ${REQUIRED_DESKTOP_ICON_RELATIVE_PATHS[index]}. `
+        + 'Prepare the file manually or run `npm run desktop:icons` before packaging.',
+      );
+    }
+  }
+  await assertDesktopIconManifestMatchesRequiredAssets(projectRoot);
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const allowedPlatforms = parsed.platform === 'all'
+    ? null
+    : ['windows', 'macos', 'linux'].includes(parsed.platform)
+      ? [parsed.platform]
+      : null;
+  if (parsed.platform !== 'all' && allowedPlatforms === null) {
+    throw new Error(`Unsupported platform filter: ${parsed.platform}`);
+  }
+
+  const { resolveDesktopHostConfig } = await import('../build/desktop/config.js');
+  const { stageDesktopPackagingOutputs } = await import('../build/desktop/packaging.js');
+
+  await assertDesktopIconAssetsPresent(PROJECT_ROOT);
+  const config = resolveDesktopHostConfig({
+    env: process.env,
+    userDataDir: resolve(PROJECT_ROOT, '.desktop-package-user'),
+  });
+  const plan = await stageDesktopPackagingOutputs(config, {
+    outputRoot: parsed.outputDir ? resolve(PROJECT_ROOT, parsed.outputDir) : undefined,
+    platforms: allowedPlatforms,
+    sidecarLayout: parsed.sidecarLayout,
+  });
+
+  process.stdout.write(JSON.stringify({
+    outputRoot: plan.outputRoot,
+    sidecarLayout: plan.sidecarLayout,
+    targets: plan.targets.map((target) => ({
+      id: target.id,
+      platform: target.platform,
+      arch: target.arch,
+      stageDirectory: target.stageDirectory,
+      installerFormats: target.installerFormats,
+    })),
+  }, null, 2));
+  process.stdout.write('\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/patch-mobile-hermesc.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { chmod, copyFile, readFile, stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
+
+const PREBUILT_DIR = resolve(
+  PROJECT_ROOT, 'mobile', '.hermes-prebuilt', 'aarch64-linux',
+);
+const PREBUILT_BINARY = resolve(PREBUILT_DIR, 'hermesc');
+const PREBUILT_VERSION = resolve(PREBUILT_DIR, '.hermesversion');
+
+const RN_HERMESC_TARGET = resolve(
+  PROJECT_ROOT, 'mobile', 'node_modules', 'react-native',
+  'sdks', 'hermesc', 'linux64-bin', 'hermesc',
+);
+const RN_HERMESVERSION = resolve(
+  PROJECT_ROOT, 'mobile', 'node_modules', 'react-native',
+  'sdks', '.hermesversion',
+);
+
+function shouldPatch() {
+  return process.platform === 'linux' && process.arch === 'arm64';
+}
+
+async function readTrimmed(path) {
+  return (await readFile(path, 'utf8')).trim();
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  if (!shouldPatch()) {
+    return;
+  }
+
+  if (!await exists(RN_HERMESC_TARGET)) {
+    process.stdout.write(
+      '[patch-mobile-hermesc] react-native hermesc not found; '
+        + 'skipping (run `npm ci --prefix mobile` first).\n',
+    );
+    return;
+  }
+
+  if (!await exists(PREBUILT_BINARY) || !await exists(PREBUILT_VERSION)) {
+    process.stderr.write(
+      '[patch-mobile-hermesc] no prebuilt aarch64 hermesc found at '
+        + `${PREBUILT_DIR}.\n`
+        + 'Build one on a Pi (see docs) and commit it, or set CATS_SKIP_MOBILE=true.\n',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const expected = await readTrimmed(PREBUILT_VERSION);
+  const actual = await readTrimmed(RN_HERMESVERSION);
+
+  if (expected !== actual) {
+    process.stderr.write(
+      '[patch-mobile-hermesc] Hermes SHA mismatch.\n'
+        + `  prebuilt:     ${expected}\n`
+        + `  react-native: ${actual}\n`
+        + 'Rebuild hermesc against the new SHA and refresh '
+        + 'mobile/.hermes-prebuilt/aarch64-linux/.\n',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  await copyFile(PREBUILT_BINARY, RN_HERMESC_TARGET);
+  await chmod(RN_HERMESC_TARGET, 0o755);
+  process.stdout.write(
+    `[patch-mobile-hermesc] patched ${RN_HERMESC_TARGET} with aarch64 build `
+      + `(Hermes ${actual.slice(0, 16)}…).\n`,
+  );
+}
+
+void main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});