@cats-inc/cats-platform 0.1.1 → 0.1.5

package/scripts/generate-desktop-release-descriptor.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+//
+// Script: generate-desktop-release-descriptor.mjs
+// Description: Emit the non-secret provenance descriptor that marks a packaged
+//              build as an official tag-gated desktop release. The desktop
+//              host refuses to advertise self-update without it.
+//
+// Usage: node scripts/generate-desktop-release-descriptor.mjs [options]
+//
+// Options:
+//   --tag <vX.Y.Z>        Release tag. Defaults to GITHUB_REF_NAME.
+//   --commit <sha>        Source commit. Defaults to GITHUB_SHA.
+//   --repository <o/r>    GitHub owner/repo. Defaults to GITHUB_REPOSITORY.
+//   --platform <windows|macos|linux>
+//                         Target platform. Defaults to the current platform.
+//   --output <path>       Descriptor path. Defaults to the packaged location.
+//   --help                Show this help text.
+//
+// The descriptor contains no secrets. It is provenance only: which tag, which
+// commit, which platform, which channel, and which update provider produced
+// the package. Local packaging never generates it.
+
+import process from 'node:process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { parseStableReleaseTag } from './validate-release-version.mjs';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
+
+// The descriptor ships inside build/desktop, which package.json already lists
+// in build.files, so it lands in the asar without extra packaging rules.
+export const DESCRIPTOR_RELATIVE_PATH = 'build/desktop/release-descriptor.json';
+
+export const DESCRIPTOR_SCHEMA_VERSION = 1;
+
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+const GITHUB_REPOSITORY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+const PLATFORM_ALIASES = {
+  windows: 'windows',
+  win32: 'windows',
+  win: 'windows',
+  macos: 'macos',
+  darwin: 'macos',
+  mac: 'macos',
+  linux: 'linux',
+};
+
+function printHelp() {
+  process.stdout.write(`Usage: node scripts/generate-desktop-release-descriptor.mjs [options]
+
+Options:
+  --tag <vX.Y.Z>        Release tag. Defaults to GITHUB_REF_NAME.
+  --commit <sha>        Source commit. Defaults to GITHUB_SHA.
+  --repository <o/r>    GitHub owner/repo. Defaults to GITHUB_REPOSITORY.
+  --platform <windows|macos|linux>
+                        Target platform. Defaults to the current platform.
+  --output <path>       Descriptor path. Defaults to ${DESCRIPTOR_RELATIVE_PATH}.
+  --help                Show this help text.
+
+Writes the non-secret official release descriptor consumed by the desktop
+update capability check. Local packaging must not run this script.
+`);
+}
+
+// Explicit rather than derived from the flag name, because --runtime-commit
+// does not slice into a valid camelCase key.
+const VALUE_FLAGS = {
+  '--tag': 'tag',
+  '--commit': 'commit',
+  '--repository': 'repository',
+  '--platform': 'platform',
+  '--runtime-commit': 'runtimeCommit',
+  '--kind': 'kind',
+  '--output': 'output',
+};
+
+export const RELEASE_KINDS = ['official', 'preview'];
+
+export function resolveDescriptorPlatform(value) {
+  const candidate = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return PLATFORM_ALIASES[candidate] ?? null;
+}
+
+export function parseArgs(argv, env = process.env) {
+  const options = {
+    help: false,
+    tag: (env.GITHUB_REF_NAME ?? '').trim(),
+    commit: (env.GITHUB_SHA ?? '').trim(),
+    repository: (env.GITHUB_REPOSITORY ?? '').trim(),
+    platform: env.CATS_DESKTOP_RELEASE_PLATFORM ?? process.platform,
+    runtimeCommit: (env.CATS_DESKTOP_RUNTIME_COMMIT ?? '').trim(),
+    // Official unless the caller says otherwise, so a missing flag can never
+    // silently downgrade a stable release into an unsigned preview.
+    kind: (env.CATS_DESKTOP_RELEASE_KIND ?? 'official').trim(),
+    output: DESCRIPTOR_RELATIVE_PATH,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--help' || value === '-h') {
+      return { ...options, help: true };
+    }
+    const key = VALUE_FLAGS[value];
+    if (key !== undefined) {
+      options[key] = (argv[index + 1] ?? '').trim();
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown option: ${value}`);
+  }
+
+  return options;
+}
+
+/**
+ * Builds the descriptor and reports every invalid input at once. Returning
+ * problems instead of throwing keeps the release workflow output readable when
+ * more than one environment variable is missing.
+ */
+export function buildReleaseDescriptor({
+  tag,
+  commit,
+  repository,
+  platform,
+  runtimeCommit,
+  kind = 'official',
+  generatedAt = null,
+} = {}) {
+  const problems = [];
+
+  const normalizedKind = typeof kind === 'string' ? kind.trim().toLowerCase() : '';
+  if (!RELEASE_KINDS.includes(normalizedKind)) {
+    problems.push({
+      code: 'descriptor_kind_invalid',
+      message: `Release kind '${kind ?? ''}' is not official or preview.`,
+    });
+  }
+
+  const parsedTag = parseStableReleaseTag(tag);
+  if (!parsedTag.ok) {
+    problems.push({ code: `descriptor_${parsedTag.code}`, message: parsedTag.message });
+  }
+
+  const normalizedCommit = typeof commit === 'string' ? commit.trim().toLowerCase() : '';
+  if (!COMMIT_SHA.test(normalizedCommit)) {
+    problems.push({
+      code: 'descriptor_commit_invalid',
+      message: `Source commit '${commit ?? ''}' is not a full 40-character sha.`,
+    });
+  }
+
+  const normalizedRepository = typeof repository === 'string' ? repository.trim() : '';
+  if (!GITHUB_REPOSITORY.test(normalizedRepository)) {
+    problems.push({
+      code: 'descriptor_repository_invalid',
+      message: `Repository '${repository ?? ''}' is not in owner/name form.`,
+    });
+  }
+
+  const normalizedPlatform = resolveDescriptorPlatform(platform);
+  if (normalizedPlatform === null) {
+    problems.push({
+      code: 'descriptor_platform_invalid',
+      message: `Platform '${platform ?? ''}' is not windows, macos, or linux.`,
+    });
+  }
+
+  // The packaged runtime is a separate repository, so the platform commit
+  // alone does not identify what shipped. Recording it makes a re-run of the
+  // same Cats tag verifiable rather than merely hopeful.
+  const normalizedRuntimeCommit = typeof runtimeCommit === 'string'
+    ? runtimeCommit.trim().toLowerCase()
+    : '';
+  if (!COMMIT_SHA.test(normalizedRuntimeCommit)) {
+    problems.push({
+      code: 'descriptor_runtime_commit_invalid',
+      message: `Runtime commit '${runtimeCommit ?? ''}' is not a full 40-character sha.`,
+    });
+  }
+
+  if (problems.length > 0) {
+    return { ok: false, descriptor: null, problems };
+  }
+
+  return {
+    ok: true,
+    problems: [],
+    descriptor: {
+      schemaVersion: DESCRIPTOR_SCHEMA_VERSION,
+      kind: normalizedKind,
+      tag: parsedTag.tag,
+      version: parsedTag.version,
+      commit: normalizedCommit,
+      platform: normalizedPlatform,
+      // SPEC-111 restricts Phase 1 publishing to the stable channel, so the
+      // descriptor states it rather than accepting it as an input.
+      channel: 'stable',
+      provider: 'github_release',
+      repository: normalizedRepository,
+      runtimeCommit: normalizedRuntimeCommit,
+      generatedAt,
+    },
+  };
+}
+
+export function serializeReleaseDescriptor(descriptor) {
+  return `${JSON.stringify(descriptor, null, 2)}\n`;
+}
+
+export async function writeReleaseDescriptor(descriptor, outputPath, projectRoot = PROJECT_ROOT) {
+  const absolutePath = resolve(projectRoot, outputPath);
+  await mkdir(dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, serializeReleaseDescriptor(descriptor), 'utf8');
+  return absolutePath;
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const result = buildReleaseDescriptor({
+    tag: parsed.tag,
+    commit: parsed.commit,
+    repository: parsed.repository,
+    platform: parsed.platform,
+    runtimeCommit: parsed.runtimeCommit,
+    kind: parsed.kind,
+    generatedAt: new Date().toISOString(),
+  });
+
+  if (!result.ok) {
+    for (const problem of result.problems) {
+      process.stderr.write(`[release-descriptor] ${problem.code}: ${problem.message}\n`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const writtenPath = await writeReleaseDescriptor(result.descriptor, parsed.output);
+  process.stdout.write(
+    `[release-descriptor] wrote ${result.descriptor.tag} `
+      + `(${result.descriptor.platform}) to ${writtenPath}\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/validate-release-assets.mjs

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+//
+// Script: validate-release-assets.mjs
+// Description: Verify that every file referenced by the generated update
+//              metadata was actually produced, and that each platform's
+//              primary user-facing artifact is present, before a draft
+//              GitHub Release is published.
+//
+// Usage: node scripts/validate-release-assets.mjs --root <dir>
+//
+// Options:
+//   --root <dir>   Directory to scan recursively. Defaults to release/.
+//   --json         Emit the machine-readable result instead of prose.
+//   --help         Show this help text.
+//
+// Exit codes:
+//   0  every required artifact and every referenced file exists
+//   1  metadata is missing, unreadable, or references a file that was not built
+
+import process from 'node:process';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import yaml from 'js-yaml';
+
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+const PROJECT_ROOT = resolve(dirname(SCRIPT_PATH), '..');
+
+/**
+ * electron-updater publishes one metadata file per platform. Each names the
+ * primary artifact the updater will download, so a missing metadata file means
+ * that platform cannot self-update even if its installer uploaded fine.
+ */
+export const DESKTOP_RELEASE_MATRIX = [
+  { platform: 'windows', formats: ['nsis'], arches: ['x64'] },
+  // macOS ships x64 only; Apple Silicon runs it under Rosetta 2.
+  { platform: 'macos', formats: ['dmg', 'zip'], arches: ['x64'] },
+  // Linux ships an arm64 .deb. electron-updater installs it with dpkg, which
+  // needs elevation -- unlike the per-user Windows path.
+  { platform: 'linux', formats: ['deb'], arches: ['arm64'] },
+];
+
+const METADATA_BASENAMES = {
+  windows: 'latest',
+  macos: 'latest-mac',
+  linux: 'latest-linux',
+};
+
+/**
+ * Derives the channel file each platform will emit.
+ *
+ * electron-builder suffixes the name with the architecture for anything other
+ * than x64, so an arm64 Linux target writes `latest-linux-arm64.yml`. Hardcoding
+ * the three unsuffixed names meant a retarget reported the real file as an
+ * unknown artifact *and* the expected file as missing -- two errors for one
+ * naming rule.
+ */
+export function expectedMetadataFiles(matrix = DESKTOP_RELEASE_MATRIX) {
+  return matrix.map((entry) => {
+    const base = METADATA_BASENAMES[entry.platform];
+    const [arch] = entry.arches;
+    return arch === 'x64' || arch === 'universal' ? `${base}.yml` : `${base}-${arch}.yml`;
+  });
+}
+
+export const UPDATE_METADATA_FILES = expectedMetadataFiles();
+
+export const PRIMARY_ARTIFACT_PATTERNS = [
+  { platform: 'windows', pattern: /\.exe$/iu },
+  { platform: 'macos', pattern: /\.dmg$/iu },
+  { platform: 'linux', pattern: /\.deb$/iu },
+];
+
+function printHelp() {
+  process.stdout.write(`Usage: node scripts/validate-release-assets.mjs [options]
+
+Options:
+  --root <dir>   Directory to scan recursively. Defaults to release/.
+  --json         Emit the machine-readable result instead of prose.
+  --help         Show this help text.
+
+Fails when generated update metadata references a file that is not present, or
+when a platform's primary user-facing artifact is missing.
+`);
+}
+
+export function parseArgs(argv) {
+  const options = { help: false, root: 'release', json: false };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--help' || value === '-h') {
+      return { ...options, help: true };
+    }
+    if (value === '--root') {
+      options.root = (argv[index + 1] ?? '').trim() || 'release';
+      index += 1;
+      continue;
+    }
+    if (value === '--json') {
+      options.json = true;
+      continue;
+    }
+    throw new Error(`Unknown option: ${value}`);
+  }
+
+  return options;
+}
+
+/**
+ * Collects the file names referenced by one metadata document. Both the
+ * top-level `path` and each `files[].url` are checked, because electron-updater
+ * reads whichever the client version supports.
+ */
+export function collectReferencedFiles(document) {
+  if (typeof document !== 'object' || document === null) {
+    return [];
+  }
+
+  const referenced = new Set();
+  const record = document;
+
+  if (typeof record.path === 'string' && record.path.trim() !== '') {
+    referenced.add(basename(decodeURIComponent(record.path.trim())));
+  }
+
+  if (Array.isArray(record.files)) {
+    for (const entry of record.files) {
+      if (typeof entry?.url === 'string' && entry.url.trim() !== '') {
+        referenced.add(basename(decodeURIComponent(entry.url.trim())));
+      }
+    }
+  }
+
+  return [...referenced];
+}
+
+/**
+ * The declared release set.
+ *
+ * This is the single source of truth for what an official release may contain.
+ * It is not a statement that other formats or architectures are undesirable —
+ * it is a statement of what this release publishes, so `--publish always`
+ * cannot quietly upload something the release page never promised.
+ *
+ * Widening the release set is one edit here plus the matching workflow matrix
+ * entry. A drift test keeps the two aligned, so adding, say, a Linux arm64
+ * AppImage is a deliberate two-line change rather than something the validator
+ * refuses on principle.
+ */
+const FORMAT_EXTENSIONS = {
+  nsis: ['.exe'],
+  dmg: ['.dmg'],
+  // The updater archive is named from this repository's artifactName template,
+  // which produces Cats-<version>-x64.zip rather than the -mac.zip default some
+  // electron-builder setups emit. The name carries no platform marker, so match
+  // it by extension and rely on the per-platform format list above.
+  zip: ['.zip'],
+  AppImage: ['.AppImage'],
+  deb: ['.deb'],
+  'tar.gz': ['.tar.gz'],
+  pkg: ['.pkg'],
+};
+
+// electron-builder spells the same architecture differently per target.
+const ARCH_TOKENS = {
+  x64: ['x64', 'x86_64', 'amd64'],
+  arm64: ['arm64', 'aarch64'],
+  ia32: ['ia32', 'i386'],
+  armv7l: ['armv7l'],
+  universal: ['universal'],
+};
+
+const ALL_ARCH_TOKENS = Object.values(ARCH_TOKENS).flat();
+
+function releasedExtensions(matrix = DESKTOP_RELEASE_MATRIX) {
+  return matrix.flatMap((entry) => entry.formats.flatMap(
+    (format) => FORMAT_EXTENSIONS[format] ?? [],
+  ));
+}
+
+/**
+ * Resolves which platform an artifact belongs to from its extension.
+ *
+ * Architecture has to be judged per platform, not across the whole matrix. With
+ * Windows on x64 and Linux on arm64, a flattened token list accepts an x64 .deb
+ * and an arm64 .exe -- each is released *somewhere*, just not where it was built.
+ */
+function platformForArtifact(name, matrix = DESKTOP_RELEASE_MATRIX) {
+  const lowered = stripBlockmap(name).toLowerCase();
+  for (const entry of matrix) {
+    for (const format of entry.formats) {
+      for (const extension of FORMAT_EXTENSIONS[format] ?? []) {
+        if (lowered.endsWith(extension.toLowerCase())) {
+          return entry;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function archTokensFor(entry) {
+  return entry.arches.flatMap((arch) => ARCH_TOKENS[arch] ?? [arch]);
+}
+
+function isUpdateMetadata(name) {
+  return UPDATE_METADATA_FILES.includes(name);
+}
+
+function stripBlockmap(name) {
+  return name.endsWith('.blockmap') ? name.slice(0, -'.blockmap'.length) : name;
+}
+
+export function resolveMissingPrimaryArtifacts(fileNames) {
+  return PRIMARY_ARTIFACT_PATTERNS
+    .filter(({ pattern }) => !fileNames.some((name) => pattern.test(name)))
+    .map(({ platform }) => platform);
+}
+
+/**
+ * Flags artifacts whose format is not part of the declared release set.
+ * Update metadata and the blockmaps that accompany a released artifact are
+ * always allowed.
+ */
+export function resolveDisallowedArtifacts(fileNames, matrix = DESKTOP_RELEASE_MATRIX) {
+  const extensions = releasedExtensions(matrix);
+
+  return fileNames.filter((name) => {
+    if (isUpdateMetadata(name)) {
+      return false;
+    }
+    const base = stripBlockmap(name);
+    return !extensions.some((extension) => base.toLowerCase().endsWith(extension.toLowerCase()));
+  });
+}
+
+/**
+ * Flags artifacts built for an architecture the declared release set does not
+ * include. An artifact whose name carries no recognizable architecture token is
+ * left alone rather than guessed at.
+ */
+export function resolveUnreleasedArchitectureArtifacts(
+  fileNames,
+  matrix = DESKTOP_RELEASE_MATRIX,
+) {
+  return fileNames.filter((name) => {
+    if (isUpdateMetadata(name)) {
+      return false;
+    }
+    const entry = platformForArtifact(name, matrix);
+    if (entry === null) {
+      // Its format is not released at all; resolveDisallowedArtifacts owns that.
+      return false;
+    }
+    const released = archTokensFor(entry).map((token) => token.toLowerCase());
+    const lowered = name.toLowerCase();
+    const present = ALL_ARCH_TOKENS.filter(
+      (token) => new RegExp(`(^|[-_.])${token}([-_.]|$)`, 'iu').test(lowered),
+    );
+    if (present.length === 0) {
+      return false;
+    }
+    return !present.some((token) => released.includes(token.toLowerCase()));
+  });
+}
+
+export function resolveMissingMetadataFiles(fileNames) {
+  const present = new Set(fileNames);
+  return UPDATE_METADATA_FILES.filter((name) => !present.has(name));
+}
+
+async function listFilesRecursively(root) {
+  const found = [];
+
+  async function walk(directory) {
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const entryPath = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await walk(entryPath);
+        continue;
+      }
+      found.push(entryPath);
+    }
+  }
+
+  const rootStat = await stat(root).catch(() => null);
+  if (rootStat === null) {
+    return [];
+  }
+  await walk(root);
+  return found;
+}
+
+export function validateReleaseAssets({ files, metadataDocuments }) {
+  const problems = [];
+  const fileNames = files.map((path) => basename(path));
+
+  for (const platform of resolveMissingPrimaryArtifacts(fileNames)) {
+    problems.push({
+      code: 'primary_artifact_missing',
+      message: `No primary user-facing artifact was produced for ${platform}.`,
+    });
+  }
+
+  for (const name of resolveMissingMetadataFiles(fileNames)) {
+    problems.push({
+      code: 'update_metadata_missing',
+      message: `Update metadata ${name} was not produced.`,
+    });
+  }
+
+  for (const name of resolveDisallowedArtifacts(fileNames)) {
+    problems.push({
+      code: 'artifact_outside_release_contract',
+      message: `${name} is not one of the declared release artifacts. `
+        + 'Add its format to DESKTOP_RELEASE_MATRIX if it should ship.',
+    });
+  }
+
+  for (const name of resolveUnreleasedArchitectureArtifacts(fileNames)) {
+    problems.push({
+      code: 'artifact_architecture_not_released',
+      message: `${name} targets an architecture the declared release set does not include. `
+        + 'Add it to DESKTOP_RELEASE_MATRIX if it should ship.',
+    });
+  }
+
+  const present = new Set(fileNames);
+  for (const { name, document, error } of metadataDocuments) {
+    if (error) {
+      problems.push({
+        code: 'update_metadata_unreadable',
+        message: `Update metadata ${name} could not be parsed: ${error}`,
+      });
+      continue;
+    }
+
+    const referenced = collectReferencedFiles(document);
+    if (referenced.length === 0) {
+      problems.push({
+        code: 'update_metadata_empty',
+        message: `Update metadata ${name} references no artifact.`,
+      });
+      continue;
+    }
+
+    for (const target of referenced) {
+      if (!present.has(target)) {
+        problems.push({
+          code: 'referenced_artifact_missing',
+          message: `Update metadata ${name} references ${target}, which was not produced.`,
+        });
+      }
+    }
+  }
+
+  return { ok: problems.length === 0, problems, fileNames: [...present].sort() };
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  if (parsed.help) {
+    printHelp();
+    return;
+  }
+
+  const root = resolve(PROJECT_ROOT, parsed.root);
+  const files = await listFilesRecursively(root);
+
+  const metadataDocuments = [];
+  for (const path of files) {
+    if (!UPDATE_METADATA_FILES.includes(basename(path))) {
+      continue;
+    }
+    try {
+      metadataDocuments.push({
+        name: basename(path),
+        document: yaml.load(await readFile(path, 'utf8')),
+        error: null,
+      });
+    } catch (error) {
+      metadataDocuments.push({
+        name: basename(path),
+        document: null,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  const result = validateReleaseAssets({ files, metadataDocuments });
+
+  if (parsed.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else if (result.ok) {
+    process.stdout.write(
+      `[validate-release-assets] ${result.fileNames.length} files verified in ${root}.\n`,
+    );
+  } else {
+    for (const problem of result.problems) {
+      process.stderr.write(`[validate-release-assets] ${problem.code}: ${problem.message}\n`);
+    }
+  }
+
+  if (!result.ok) {
+    process.exitCode = 1;
+  }
+}
+
+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;
+  });
+}