@springfield/ham-radio-utils 4.16.1 → 4.17.0

package/dist/pack/ref-closure.js

@@ -0,0 +1,93 @@
+/**
+ * Transitive relative `$ref` closure for one radio config.
+ * Matches the file set `pack:release` zips for that model: shared schemas and
+ * memory maps the config reaches, and not sibling radios.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+/**
+ * @returns Sorted repo-relative paths, including `startRelative`
+ */
+export function collectRefClosure(moduleRoot, startRelative) {
+    const included = new Set([startRelative]);
+    const pending = [startRelative];
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (!current) {
+            continue;
+        }
+        const text = readWorkingTreeText(moduleRoot, current);
+        if (text === undefined) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            continue;
+        }
+        const fromDirectory = dirname(join(moduleRoot, current));
+        for (const refPath of localRefTargets(parsed)) {
+            const absolutePath = resolve(fromDirectory, refPath);
+            const relativePath = toRepoRelative(moduleRoot, absolutePath);
+            if (relativePath === undefined) {
+                throw new Error(`${current} $ref escapes the repository: ${refPath}`);
+            }
+            if (!included.has(relativePath)) {
+                included.add(relativePath);
+                pending.push(relativePath);
+            }
+        }
+    }
+    return [...included].sort();
+}
+export function readWorkingTreeText(moduleRoot, relativePath) {
+    const absolutePath = join(moduleRoot, relativePath);
+    if (!existsSync(absolutePath)) {
+        return undefined;
+    }
+    return readFileSync(absolutePath, 'utf8');
+}
+export function localRefTargets(value, into = []) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            localRefTargets(item, into);
+        }
+        return into;
+    }
+    if (!value || typeof value !== 'object') {
+        return into;
+    }
+    const record = value;
+    if (typeof record.$ref === 'string') {
+        const refPath = filePathFromRef(record.$ref);
+        if (refPath) {
+            into.push(refPath);
+        }
+    }
+    for (const child of Object.values(record)) {
+        localRefTargets(child, into);
+    }
+    return into;
+}
+/**
+ * Path portion of a relative file `$ref`, without a JSON pointer.
+ * Fragment-only refs and absolute URIs are ignored.
+ */
+export function filePathFromRef(ref) {
+    if (ref.length === 0 || ref.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(ref)) {
+        return undefined;
+    }
+    const hashIndex = ref.indexOf('#');
+    const refPath = hashIndex === -1 ? ref : ref.slice(0, hashIndex);
+    return refPath.length > 0 ? refPath : undefined;
+}
+function toRepoRelative(rootDirectory, absolutePath) {
+    const relativePath = relative(rootDirectory, absolutePath);
+    if (relativePath === '' || relativePath.startsWith('..') || relativePath.includes(`${sep}..`)) {
+        return undefined;
+    }
+    return relativePath.split(sep).join('/');
+}
+//# sourceMappingURL=ref-closure.js.map

package/dist/pack/ref-closure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-closure.js","sourceRoot":"","sources":["../../src/pack/ref-closure.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Transitive relative `$ref` closure for one radio config.\n * Matches the file set `pack:release` zips for that model: shared schemas and\n * memory maps the config reaches, and not sibling radios.\n */\nimport { existsSync, readFileSync } from 'node:fs';\nimport { dirname, join, relative, resolve, sep } from 'node:path';\n\n/**\n * @returns Sorted repo-relative paths, including `startRelative`\n */\nexport function collectRefClosure(moduleRoot: string, startRelative: string): string[] {\n  const included = new Set<string>([startRelative]);\n  const pending = [startRelative];\n\n  while (pending.length > 0) {\n    const current = pending.pop();\n\n    if (!current) {\n      continue;\n    }\n\n    const text = readWorkingTreeText(moduleRoot, current);\n\n    if (text === undefined) {\n      continue;\n    }\n\n    let parsed: unknown;\n\n    try {\n      parsed = JSON.parse(text) as unknown;\n    } catch {\n      continue;\n    }\n\n    const fromDirectory = dirname(join(moduleRoot, current));\n\n    for (const refPath of localRefTargets(parsed)) {\n      const absolutePath = resolve(fromDirectory, refPath);\n      const relativePath = toRepoRelative(moduleRoot, absolutePath);\n\n      if (relativePath === undefined) {\n        throw new Error(`${current} $ref escapes the repository: ${refPath}`);\n      }\n\n      if (!included.has(relativePath)) {\n        included.add(relativePath);\n        pending.push(relativePath);\n      }\n    }\n  }\n\n  return [...included].sort();\n}\n\nexport function readWorkingTreeText(moduleRoot: string, relativePath: string): string | undefined {\n  const absolutePath = join(moduleRoot, relativePath);\n\n  if (!existsSync(absolutePath)) {\n    return undefined;\n  }\n\n  return readFileSync(absolutePath, 'utf8');\n}\n\nexport function localRefTargets(value: unknown, into: string[] = []): string[] {\n  if (Array.isArray(value)) {\n    for (const item of value) {\n      localRefTargets(item, into);\n    }\n\n    return into;\n  }\n\n  if (!value || typeof value !== 'object') {\n    return into;\n  }\n\n  const record = value as Record<string, unknown>;\n\n  if (typeof record.$ref === 'string') {\n    const refPath = filePathFromRef(record.$ref);\n\n    if (refPath) {\n      into.push(refPath);\n    }\n  }\n\n  for (const child of Object.values(record)) {\n    localRefTargets(child, into);\n  }\n\n  return into;\n}\n\n/**\n * Path portion of a relative file `$ref`, without a JSON pointer.\n * Fragment-only refs and absolute URIs are ignored.\n */\nexport function filePathFromRef(ref: string): string | undefined {\n  if (ref.length === 0 || ref.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(ref)) {\n    return undefined;\n  }\n\n  const hashIndex = ref.indexOf('#');\n  const refPath = hashIndex === -1 ? ref : ref.slice(0, hashIndex);\n\n  return refPath.length > 0 ? refPath : undefined;\n}\n\nfunction toRepoRelative(rootDirectory: string, absolutePath: string): string | undefined {\n  const relativePath = relative(rootDirectory, absolutePath);\n\n  if (relativePath === '' || relativePath.startsWith('..') || relativePath.includes(`${sep}..`)) {\n    return undefined;\n  }\n\n  return relativePath.split(sep).join('/');\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@springfield/ham-radio-utils",
-  "version": "4.16.1",
+  "version": "4.17.0",
   "author": "Bryan Hunt",
   "license": "MIT",
   "readme": "README.md",
@@ -11,6 +11,9 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "ham-radio-pack-beta": "./dist/pack/pack-beta-cli.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/springfield-ham-radio/ham-radio-utils.git"
@@ -25,6 +28,7 @@
     "lint": "oxlint",
     "lint:fix": "oxlint --fix --fix-suggestions",
     "release": "semantic-release",
+    "pack:beta": "ham-radio-pack-beta",
     "prepare": "husky && yarn build",
     "test": "yarn test:unit",
     "test:unit": "vitest run test/unit"

package/src/index.ts

@@ -17,6 +17,29 @@ export * from './utils/to-hex-words.js';
 export * from './utils/ui-logger.js';
 export * from './utils/ui-logger-factory.js';
 
+export {
+  BETA_COUNTER_PATTERN,
+  BETA_VERSION_PATTERN,
+  MAX_BETA_ZIP_BYTES,
+  STRICT_SEMVER_PATTERN,
+  assertStrictSemver,
+  closurePathsForConfig,
+  compareDriverVersions,
+  compareToCatalogVersion,
+  expectedBetaZipName,
+  formatBetaPackOutput,
+  listConfigDescriptors,
+  packBetaZip,
+  packedBetaVersion,
+  parseBetaCounter,
+  parseConfigDescriptor,
+  runPackBetaCli,
+  shortGitSha,
+  stageClosureWithBetaVersion,
+  validateBetaDescriptor,
+} from './pack/pack-beta.js';
+export type { PackBetaCliIo, PackBetaOptions, PackBetaResult, RadioModuleConfigDescriptor } from './pack/pack-beta.js';
+
 // Export the radio protocol schema
 export { default as radioProtocolSchema } from './schemas/radio-protocol-schema.json' with { type: 'json' };
 export { default as radioMemoryMapSchema } from './schemas/radio-memory-map-schema.json' with { type: 'json' };

package/src/pack/driver-semver.ts

@@ -0,0 +1,112 @@
+/**
+ * Driver version precedence for local beta zips against a strict catalog version.
+ * ADR 0010: registry `compareSemver` stays numeric-only. This helper is the
+ * prerelease rule HamBench applies to install directories.
+ *
+ * - `1.11.1-beta.1` is older than catalog `1.11.1`
+ * - `1.11.2-beta.1` is newer than catalog `1.11.1`
+ * - among betas, `n` is numeric (`2` is less than `10`)
+ */
+
+export const STRICT_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
+export const BETA_COUNTER_PATTERN = /^[1-9]\d*$/;
+export const BETA_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)-beta\.([1-9]\d*)$/;
+
+export interface ParsedDriverVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  beta?: number;
+}
+
+export function assertStrictSemver(value: string, fieldLabel: string): void {
+  if (!STRICT_SEMVER_PATTERN.test(value)) {
+    throw new Error(`${fieldLabel} must be strict major.minor.patch (no prerelease or build metadata)`);
+  }
+}
+
+export function parseBetaCounter(raw: string | undefined): number {
+  if (raw === undefined) {
+    return 1;
+  }
+
+  if (!BETA_COUNTER_PATTERN.test(raw)) {
+    throw new Error('beta counter n must be a positive integer with no leading zero');
+  }
+
+  return Number(raw);
+}
+
+export function packedBetaVersion(baseVersion: string, n: number): string {
+  return `${baseVersion}-beta.${n}`;
+}
+
+export function parseDriverVersion(version: string): ParsedDriverVersion {
+  const trimmed = version.trim();
+  const betaMatch = BETA_VERSION_PATTERN.exec(trimmed);
+
+  if (betaMatch) {
+    return {
+      major: Number(betaMatch[1]),
+      minor: Number(betaMatch[2]),
+      patch: Number(betaMatch[3]),
+      beta: Number(betaMatch[4]),
+    };
+  }
+
+  if (!STRICT_SEMVER_PATTERN.test(trimmed)) {
+    throw new Error(`driver version must be strict major.minor.patch or major.minor.patch-beta.n: ${version}`);
+  }
+
+  const [major, minor, patch] = trimmed.split('.').map((part) => Number(part));
+
+  return { major: major ?? 0, minor: minor ?? 0, patch: patch ?? 0 };
+}
+
+/**
+ * Positive when `left` is newer than `right`.
+ * A release is newer than a beta of the same major.minor.patch.
+ */
+export function compareDriverVersions(left: string, right: string): number {
+  const a = parseDriverVersion(left);
+  const b = parseDriverVersion(right);
+
+  if (a.major !== b.major) {
+    return a.major - b.major;
+  }
+
+  if (a.minor !== b.minor) {
+    return a.minor - b.minor;
+  }
+
+  if (a.patch !== b.patch) {
+    return a.patch - b.patch;
+  }
+
+  if (a.beta === undefined && b.beta === undefined) {
+    return 0;
+  }
+
+  if (a.beta === undefined) {
+    return 1;
+  }
+
+  if (b.beta === undefined) {
+    return -1;
+  }
+
+  return a.beta - b.beta;
+}
+
+/**
+ * Compare an installed driver version to a catalog `major.minor.patch`.
+ * Catalog strings are strict; prerelease catalog versions are rejected.
+ * Negative means the install is older than the catalog entry (HamBench offers Update).
+ */
+export function compareToCatalogVersion(installedVersion: string, catalogVersion: string): number {
+  if (!STRICT_SEMVER_PATTERN.test(catalogVersion)) {
+    throw new Error(`catalog version must be strict major.minor.patch: ${catalogVersion}`);
+  }
+
+  return compareDriverVersions(installedVersion, catalogVersion);
+}

package/src/pack/pack-beta-cli.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runPackBetaCli } from './pack-beta.js';
+
+const exitCode = runPackBetaCli(process.argv.slice(2), process.cwd());
+process.exit(exitCode);

package/src/pack/pack-beta.ts

@@ -0,0 +1,340 @@
+/**
+ * Build one local beta driver zip (ADR 0010).
+ *
+ * Usage from a radio module repo: `yarn pack:beta <modelId> [n]`
+ *   n — positive beta counter (default 1, no leading zero).
+ *
+ * Writes `dist-release/radio-module-<modelId>-<version>-beta.<n>.zip` without
+ * modifying the working tree, catalog entries, or other zips in `dist-release/`.
+ * Does not call GitHub and does not skip a model that already has a release asset.
+ */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { collectRefClosure } from './ref-closure.js';
+import { assertStrictSemver, BETA_COUNTER_PATTERN, packedBetaVersion, parseBetaCounter } from './driver-semver.js';
+
+export {
+  assertStrictSemver,
+  BETA_COUNTER_PATTERN,
+  BETA_VERSION_PATTERN,
+  compareDriverVersions,
+  compareToCatalogVersion,
+  packedBetaVersion,
+  parseBetaCounter,
+  STRICT_SEMVER_PATTERN,
+} from './driver-semver.js';
+
+export const MAX_BETA_ZIP_BYTES = 1024 * 1024;
+
+export interface RadioModuleConfigDescriptor {
+  fileName: string;
+  relativeConfig: string;
+  modelId: string;
+  name: string;
+  configVersion: string;
+  minApiVersion: string;
+  manufacturer: string;
+  parsed: unknown;
+}
+
+export interface PackBetaOptions {
+  outputDirectory?: string;
+}
+
+export interface PackBetaResult {
+  zipPath: string;
+  zipName: string;
+  modelId: string;
+  baseVersion: string;
+  packedVersion: string;
+  size: number;
+  sha256: string;
+  gitSha?: string;
+}
+
+export function expectedBetaZipName(modelId: string, baseVersion: string, n: number): string {
+  return `radio-module-${modelId}-${baseVersion}-beta.${n}.zip`;
+}
+
+export function packBetaZip(moduleRoot: string, modelId: string, n = 1, options: PackBetaOptions = {}): PackBetaResult {
+  if (!Number.isSafeInteger(n) || !BETA_COUNTER_PATTERN.test(String(n))) {
+    throw new Error('beta counter n must be a positive integer with no leading zero');
+  }
+
+  const descriptor = loadDescriptor(moduleRoot, modelId);
+  validateBetaDescriptor(descriptor);
+
+  const pathsToZip = closurePathsForConfig(moduleRoot, descriptor);
+  const version = packedBetaVersion(descriptor.configVersion, n);
+  const zipName = expectedBetaZipName(descriptor.modelId, descriptor.configVersion, n);
+  const outputDirectory = options.outputDirectory ?? join(moduleRoot, 'dist-release');
+  const zipPath = join(outputDirectory, zipName);
+
+  mkdirSync(outputDirectory, { recursive: true });
+
+  const stagingRoot = mkdtempSync(join(tmpdir(), 'pack-beta-'));
+
+  try {
+    stageClosureWithBetaVersion(moduleRoot, stagingRoot, pathsToZip, descriptor.relativeConfig, version);
+    createZipFromStaging(stagingRoot, zipPath, pathsToZip);
+  } finally {
+    rmSync(stagingRoot, { recursive: true, force: true });
+  }
+
+  const size = statSync(zipPath).size;
+
+  if (size > MAX_BETA_ZIP_BYTES) {
+    unlinkSync(zipPath);
+    throw new Error(`beta zip exceeds ${MAX_BETA_ZIP_BYTES} bytes (${size} bytes)`);
+  }
+
+  const sha256 = integrityFromFile(zipPath);
+  const gitSha = shortGitSha(moduleRoot);
+
+  return {
+    zipPath,
+    zipName,
+    modelId: descriptor.modelId,
+    baseVersion: descriptor.configVersion,
+    packedVersion: version,
+    size,
+    sha256,
+    ...(gitSha ? { gitSha } : {}),
+  };
+}
+
+export function validateBetaDescriptor(descriptor: Pick<RadioModuleConfigDescriptor, 'relativeConfig' | 'configVersion' | 'minApiVersion'>): void {
+  const { relativeConfig, configVersion, minApiVersion } = descriptor;
+
+  if (typeof configVersion !== 'string' || configVersion.length === 0) {
+    throw new Error(`${relativeConfig} is missing version`);
+  }
+
+  if (configVersion.includes('-') || configVersion.includes('+')) {
+    throw new Error(`${relativeConfig} version must not include a prerelease or build metadata suffix`);
+  }
+
+  assertStrictSemver(configVersion, `${relativeConfig} version`);
+
+  if (typeof minApiVersion !== 'string' || minApiVersion.length === 0) {
+    throw new Error(`${relativeConfig} is missing minApiVersion`);
+  }
+
+  if (minApiVersion.includes('-') || minApiVersion.includes('+')) {
+    throw new Error(`${relativeConfig} minApiVersion must not include a prerelease or build metadata suffix`);
+  }
+
+  assertStrictSemver(minApiVersion, `${relativeConfig} minApiVersion`);
+}
+
+export function listConfigDescriptors(moduleRoot: string): RadioModuleConfigDescriptor[] {
+  const configDirectory = join(moduleRoot, 'configs');
+
+  if (!existsSync(configDirectory)) {
+    throw new Error('configs directory is missing');
+  }
+
+  const manufacturerDefault = readManufacturerDefault(moduleRoot);
+
+  return readdirSync(configDirectory)
+    .filter((fileName) => fileName.endsWith('.json'))
+    .sort()
+    .map((fileName) => parseConfigDescriptor(moduleRoot, fileName, manufacturerDefault));
+}
+
+export function parseConfigDescriptor(moduleRoot: string, fileName: string, manufacturerDefault?: string): RadioModuleConfigDescriptor {
+  const relativeConfig = `configs/${fileName}`;
+  const absoluteConfig = join(moduleRoot, relativeConfig);
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(readFileSync(absoluteConfig, 'utf8')) as unknown;
+  } catch {
+    throw new Error(`${relativeConfig} is not valid JSON`);
+  }
+
+  const record = parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {};
+  const id = record.id && typeof record.id === 'object' ? (record.id as Record<string, unknown>) : {};
+  const modelId = id.model;
+  const name = id.name;
+  const configVersion = record.version;
+  const minApiVersion = record.minApiVersion;
+  const manufacturer = typeof id.manufacturer === 'string' && id.manufacturer.length > 0 ? id.manufacturer : manufacturerDefault;
+
+  if (typeof modelId !== 'string' || modelId.length === 0) {
+    throw new Error(`${relativeConfig} is missing id.model`);
+  }
+
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error(`${relativeConfig} is missing id.name`);
+  }
+
+  if (typeof configVersion !== 'string' || configVersion.length === 0) {
+    throw new Error(`${relativeConfig} is missing version`);
+  }
+
+  if (typeof minApiVersion !== 'string' || minApiVersion.length === 0) {
+    throw new Error(`${relativeConfig} is missing minApiVersion`);
+  }
+
+  if (typeof manufacturer !== 'string' || manufacturer.length === 0) {
+    throw new Error(`${relativeConfig} is missing id.manufacturer`);
+  }
+
+  const expectedFile = `configs/${modelId}.json`;
+
+  if (relativeConfig !== expectedFile) {
+    throw new Error(`${relativeConfig} must be named ${expectedFile} (id.model ${modelId})`);
+  }
+
+  return {
+    fileName,
+    relativeConfig,
+    modelId,
+    name,
+    configVersion,
+    minApiVersion,
+    manufacturer,
+    parsed,
+  };
+}
+
+export function closurePathsForConfig(moduleRoot: string, descriptor: Pick<RadioModuleConfigDescriptor, 'relativeConfig'>): string[] {
+  const paths = collectRefClosure(moduleRoot, descriptor.relativeConfig);
+
+  for (const relativePath of paths) {
+    if (!existsSync(join(moduleRoot, relativePath))) {
+      throw new Error(`${descriptor.relativeConfig} $ref target is missing: ${relativePath}`);
+    }
+  }
+
+  return paths;
+}
+
+export function stageClosureWithBetaVersion(moduleRoot: string, stagingRoot: string, relativePaths: string[], configRelative: string, version: string): void {
+  for (const relativePath of relativePaths) {
+    const sourcePath = join(moduleRoot, relativePath);
+    const destPath = join(stagingRoot, relativePath);
+
+    mkdirSync(dirname(destPath), { recursive: true });
+
+    if (relativePath === configRelative) {
+      const parsed = JSON.parse(readFileSync(sourcePath, 'utf8')) as Record<string, unknown>;
+      parsed.version = version;
+      writeFileSync(destPath, `${JSON.stringify(parsed, null, 2)}\n`);
+    } else {
+      cpSync(sourcePath, destPath);
+    }
+  }
+}
+
+export function shortGitSha(moduleRoot: string): string | undefined {
+  const result = spawnSync('git', ['rev-parse', '--short', 'HEAD'], {
+    cwd: moduleRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.status !== 0) {
+    return undefined;
+  }
+
+  const sha = result.stdout.trim();
+  return sha.length > 0 ? sha : undefined;
+}
+
+export function formatBetaPackOutput(result: Pick<PackBetaResult, 'zipPath' | 'size' | 'sha256' | 'gitSha'>): string {
+  const lines = [result.zipPath, String(result.size), result.sha256];
+
+  if (result.gitSha) {
+    lines.push(result.gitSha);
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+export interface PackBetaCliIo {
+  write(chunk: string): void;
+}
+
+export function runPackBetaCli(args: readonly string[], moduleRoot: string, stdout: PackBetaCliIo = process.stdout, stderr: PackBetaCliIo = process.stderr): number {
+  const [modelId, nArg, ...rest] = args;
+
+  if (!modelId || rest.length > 0) {
+    stderr.write('usage: yarn pack:beta <modelId> [n]\n');
+    return 1;
+  }
+
+  try {
+    const n = parseBetaCounter(nArg);
+    const result = packBetaZip(moduleRoot, modelId, n);
+    stdout.write(formatBetaPackOutput(result));
+    return 0;
+  } catch (error) {
+    stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+function loadDescriptor(moduleRoot: string, modelId: string): RadioModuleConfigDescriptor {
+  const descriptors = listConfigDescriptors(moduleRoot);
+  const descriptor = descriptors.find((entry) => entry.modelId === modelId);
+
+  if (!descriptor) {
+    const known = descriptors.map((entry) => entry.modelId).join(', ');
+    throw new Error(`unknown modelId ${modelId}; expected one of: ${known}`);
+  }
+
+  return descriptor;
+}
+
+function readManufacturerDefault(moduleRoot: string): string | undefined {
+  const packagePath = join(moduleRoot, 'package.json');
+
+  if (!existsSync(packagePath)) {
+    return undefined;
+  }
+
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as unknown;
+  } catch {
+    throw new Error('package.json is not valid JSON');
+  }
+
+  if (!parsed || typeof parsed !== 'object') {
+    return undefined;
+  }
+
+  const springfield = (parsed as Record<string, unknown>).springfield;
+
+  if (!springfield || typeof springfield !== 'object') {
+    return undefined;
+  }
+
+  const manufacturer = (springfield as Record<string, unknown>).manufacturer;
+  return typeof manufacturer === 'string' && manufacturer.length > 0 ? manufacturer : undefined;
+}
+
+function createZipFromStaging(stagingRoot: string, zipPath: string, relativePaths: string[]): void {
+  if (existsSync(zipPath)) {
+    unlinkSync(zipPath);
+  }
+
+  const zipResult = spawnSync('zip', ['-q', zipPath, ...relativePaths, '-x', '*.DS_Store'], {
+    cwd: stagingRoot,
+    encoding: 'utf8',
+  });
+
+  if (zipResult.status !== 0) {
+    throw new Error(zipResult.stderr || zipResult.stdout || 'zip failed');
+  }
+}
+
+function integrityFromFile(filePath: string): string {
+  const hash = createHash('sha256').update(readFileSync(filePath)).digest('hex');
+  return `sha256:${hash}`;
+}