@tutti-os/app-release-tools 0.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,26 @@
+# @tutti-os/app-release-tools
+
+Command-line tools for publishing Nextop workspace apps into App Center release metadata.
+
+## Commands
+
+```sh
+build-nextop-app-release --app-id vibe-design --package-dir dist/nextop-app/vibe-design --base-url https://cdn.example.test/nextop-app-releases
+build-nextop-app-catalog --release-file ./apps/vibe-design/latest.json --output ./catalog.json
+build-nextop-app-catalog --existing-catalog ./catalog.json --release-file ./apps/vibe-design/latest.json --output ./catalog.json
+verify-nextop-app-release-artifacts --release-file ./apps/vibe-design/latest.json
+verify-nextop-app-release-artifacts --catalog-file ./catalog.json --release-file ./apps/vibe-design/latest.json
+```
+
+The release command validates a complete Nextop app package, creates a zip, writes immutable `release.json`, and writes mutable `latest.json`.
+
+The catalog command merges one or more release files into `nextop.app.catalog.v1`.
+Pass `--existing-catalog` to preserve existing catalog apps and update only the
+apps represented by the release files. With `--existing-catalog`, release files
+are optional, which allows rewriting an existing catalog without changing its app
+set.
+
+The verify command checks release and catalog metadata against the referenced
+artifact downloads. When both `--catalog-file` and `--release-file` are passed,
+catalog entries for those apps must exactly match the latest release metadata
+before artifact SHA-256 and size checks run.

package/bin/build-nextop-app-catalog.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+
+import {
+  releaseToCatalogApp,
+  validateRelease
+} from "./build-nextop-app-release.mjs";
+
+const catalogSchemaVersion = "nextop.app.catalog.v1";
+
+export async function buildNextopAppCatalog(options) {
+  const existingCatalogPath = options.existingCatalogPath
+    ? path.resolve(String(options.existingCatalogPath))
+    : null;
+  const releaseFiles = normalizeReleaseFiles(options.releaseFiles);
+  const outputPath = path.resolve(
+    options.outputPath
+      ? String(options.outputPath)
+      : "dist/nextop-app-catalog/catalog.json"
+  );
+
+  const seenAppIDs = new Set();
+  const seenReleaseAppIDs = new Set();
+  const appsByID = new Map();
+
+  if (existingCatalogPath) {
+    const existingCatalog = JSON.parse(
+      await readFile(existingCatalogPath, "utf8")
+    );
+    validateCatalog(existingCatalog);
+    for (const app of existingCatalog.apps) {
+      const appID = app.manifest.appId;
+      if (seenAppIDs.has(appID)) {
+        throw new Error(`duplicate catalog appId ${appID}`);
+      }
+      seenAppIDs.add(appID);
+      appsByID.set(appID, app);
+    }
+  }
+
+  for (const releaseFile of releaseFiles) {
+    const release = JSON.parse(await readFile(releaseFile, "utf8"));
+    validateRelease(release);
+    if (seenReleaseAppIDs.has(release.appId)) {
+      throw new Error(`duplicate release appId ${release.appId}`);
+    }
+    seenReleaseAppIDs.add(release.appId);
+    if (!seenAppIDs.has(release.appId)) {
+      seenAppIDs.add(release.appId);
+    }
+    appsByID.set(release.appId, releaseToCatalogApp(release));
+  }
+
+  if (appsByID.size === 0) {
+    throw new Error(
+      "at least one release file or existing catalog app is required"
+    );
+  }
+
+  const apps = [...appsByID.values()];
+  apps.sort((left, right) =>
+    left.manifest.appId.localeCompare(right.manifest.appId)
+  );
+
+  const catalog = {
+    schemaVersion: catalogSchemaVersion,
+    apps
+  };
+
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, `${JSON.stringify(catalog, null, 2)}\n`);
+  return { outputPath, catalog };
+}
+
+function normalizeReleaseFiles(value) {
+  const files = Array.isArray(value)
+    ? value
+    : String(value ?? "")
+        .split(/[\n,]/)
+        .map((file) => file.trim())
+        .filter(Boolean);
+  return files.map((file) => path.resolve(file));
+}
+
+function validateCatalog(catalog) {
+  if (!catalog || typeof catalog !== "object") {
+    throw new Error("catalog must be an object");
+  }
+  if (catalog.schemaVersion !== catalogSchemaVersion) {
+    throw new Error(`catalog schemaVersion must be ${catalogSchemaVersion}`);
+  }
+  if (!Array.isArray(catalog.apps)) {
+    throw new Error("catalog apps must be an array");
+  }
+  for (const [index, app] of catalog.apps.entries()) {
+    if (!app || typeof app !== "object") {
+      throw new Error(`catalog apps[${index}] must be an object`);
+    }
+    if (
+      !app.manifest ||
+      typeof app.manifest !== "object" ||
+      typeof app.manifest.appId !== "string" ||
+      app.manifest.appId.trim() === ""
+    ) {
+      throw new Error(`catalog apps[${index}].manifest.appId is required`);
+    }
+  }
+}
+
+function parseArgs(argv) {
+  const result = {
+    releaseFiles: []
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--release-file") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("missing value for --release-file");
+      }
+      result.releaseFiles.push(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--existing-catalog") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("missing value for --existing-catalog");
+      }
+      result.existingCatalogPath = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--output") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("missing value for --output");
+      }
+      result.outputPath = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`unexpected argument: ${arg}`);
+  }
+  return result;
+}
+
+export async function main() {
+  const result = await buildNextopAppCatalog(parseArgs(process.argv.slice(2)));
+  process.stdout.write(`${JSON.stringify(result.catalog, null, 2)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/bin/build-nextop-app-release.mjs

@@ -0,0 +1,557 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { pathToFileURL } from "node:url";
+import { cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const manifestSchemaVersion = "nextop.app.manifest.v1";
+const cliManifestSchemaVersion = "nextop.app.cli.v1";
+const releaseSchemaVersion = "nextop.app.release.v1";
+
+export async function buildNextopAppRelease(options) {
+  const appId = requireNonEmpty(options.appId, "appId");
+  requireSafePathSegment(appId, "appId");
+  const packageDir = path.resolve(
+    requireNonEmpty(options.packageDir, "packageDir")
+  );
+  const outputDir = path.resolve(
+    options.outputDir ? String(options.outputDir) : "dist/nextop-app-release"
+  );
+  const baseUrl = normalizeBaseUrl(requireNonEmpty(options.baseUrl, "baseUrl"));
+  const publishedAt =
+    options.publishedAt || new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  const gitSha = options.gitSha || resolveGitSha();
+
+  const manifestPath = path.join(packageDir, "nextop.app.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  validateManifest(manifest, manifestPath);
+  if (manifest.appId !== appId) {
+    throw new Error(
+      `appId mismatch: input ${appId} does not match manifest ${manifest.appId}`
+    );
+  }
+
+  const version = requireNonEmpty(
+    options.version || manifest.version,
+    "version"
+  );
+  requireSafePathSegment(version, "version");
+  manifest.version = version;
+  validateManifest(manifest, manifestPath);
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  await requireExecutableFile(
+    path.join(packageDir, manifest.runtime.bootstrap)
+  );
+  await requireNonEmptyTextFile(path.join(packageDir, "AGENTS.md"));
+
+  const manifestIconPath = path.join(packageDir, manifest.icon.src);
+  await requireFile(manifestIconPath);
+  for (const locale of manifest.localizationInfo?.additionalLocales ?? []) {
+    await requireNonEmptyTextFile(path.join(packageDir, locale.file));
+  }
+  if (manifest.cli?.manifest) {
+    const cliManifestPath = path.join(packageDir, manifest.cli.manifest);
+    await requireFile(cliManifestPath);
+    validateCLIManifest(
+      JSON.parse(await readFile(cliManifestPath, "utf8")),
+      `${manifestPath}.cli.manifest`
+    );
+  }
+  const sourceIconPath = options.iconPath
+    ? path.resolve(String(options.iconPath))
+    : manifestIconPath;
+  await requireFile(sourceIconPath);
+
+  const releasePrefix = `apps/${appId}/${version}`;
+  const releaseURLPrefix = joinURLPathSegments("apps", appId, version);
+  const releaseDir = path.join(outputDir, releasePrefix);
+  await mkdir(releaseDir, { recursive: true });
+
+  const artifactName = `${appId}-${version}.zip`;
+  const artifactPath = path.join(releaseDir, artifactName);
+  createZip(packageDir, artifactPath);
+  const artifact = await fileDigestAndSize(artifactPath);
+
+  const iconName = path.basename(sourceIconPath);
+  const iconOutputPath = path.join(releaseDir, iconName);
+  await cp(sourceIconPath, iconOutputPath);
+
+  const releaseJson = {
+    schemaVersion: releaseSchemaVersion,
+    appId,
+    version,
+    name: manifest.name,
+    description: manifest.description,
+    manifest,
+    artifactUrl: `${baseUrl}/${releaseURLPrefix}/${encodeURLPathSegment(artifactName)}`,
+    artifactSha256: artifact.sha256,
+    artifactSizeBytes: artifact.size,
+    iconUrl: `${baseUrl}/${releaseURLPrefix}/${encodeURLPathSegment(iconName)}`,
+    publishedAt,
+    gitSha
+  };
+
+  await writeJson(path.join(releaseDir, "release.json"), releaseJson);
+  await mkdir(path.join(outputDir, "apps", appId), { recursive: true });
+  await writeJson(
+    path.join(outputDir, "apps", appId, "latest.json"),
+    releaseJson
+  );
+
+  return {
+    artifactPath,
+    latestJsonPath: path.join(outputDir, "apps", appId, "latest.json"),
+    releaseJsonPath: path.join(releaseDir, "release.json"),
+    release: releaseJson
+  };
+}
+
+export function validateManifest(manifest, sourceLabel = "manifest") {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error(`${sourceLabel} must be an object`);
+  }
+  for (const key of ["schemaVersion", "appId", "version", "name"]) {
+    requireManifestString(manifest, key, sourceLabel);
+  }
+  if (manifest.schemaVersion !== manifestSchemaVersion) {
+    throw new Error(
+      `${sourceLabel} schemaVersion must be ${manifestSchemaVersion}`
+    );
+  }
+  if (!manifest.icon || typeof manifest.icon !== "object") {
+    throw new Error(`${sourceLabel} icon is required`);
+  }
+  requireManifestString(manifest.icon, "type", `${sourceLabel}.icon`);
+  requireManifestString(manifest.icon, "src", `${sourceLabel}.icon`);
+  if (!isRelativePackagePath(manifest.icon.src)) {
+    throw new Error(`${sourceLabel} icon.src must be a relative package path`);
+  }
+  if (!manifest.runtime || typeof manifest.runtime !== "object") {
+    throw new Error(`${sourceLabel} runtime is required`);
+  }
+  requireManifestString(
+    manifest.runtime,
+    "bootstrap",
+    `${sourceLabel}.runtime`
+  );
+  requireManifestString(
+    manifest.runtime,
+    "healthcheckPath",
+    `${sourceLabel}.runtime`
+  );
+  if (!isRelativePackagePath(manifest.runtime.bootstrap)) {
+    throw new Error(
+      `${sourceLabel} runtime.bootstrap must be a relative package path`
+    );
+  }
+  if (!manifest.runtime.healthcheckPath.startsWith("/")) {
+    throw new Error(`${sourceLabel} runtime.healthcheckPath must start with /`);
+  }
+  validateManifestCLI(manifest.cli, sourceLabel);
+  validateLocalizationInfo(manifest.localizationInfo, sourceLabel);
+}
+
+function validateManifestCLI(cli, sourceLabel) {
+  if (cli === undefined) {
+    return;
+  }
+  if (!cli || typeof cli !== "object") {
+    throw new Error(`${sourceLabel} cli must be an object`);
+  }
+  const cliManifest = requireNonEmpty(
+    cli.manifest,
+    `${sourceLabel}.cli.manifest`
+  );
+  if (!isRelativePackagePath(cliManifest)) {
+    throw new Error(
+      `${sourceLabel}.cli.manifest must be a relative package path`
+    );
+  }
+}
+
+export function validateCLIManifest(manifest, sourceLabel = "cli manifest") {
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error(`${sourceLabel} must be an object`);
+  }
+  if (manifest.schemaVersion !== cliManifestSchemaVersion) {
+    throw new Error(
+      `${sourceLabel} schemaVersion must be ${cliManifestSchemaVersion}`
+    );
+  }
+  requireCLISegment(manifest.scope, `${sourceLabel}.scope`);
+  if (!Array.isArray(manifest.commands) || manifest.commands.length === 0) {
+    throw new Error(`${sourceLabel}.commands must be a non-empty array`);
+  }
+  const seenPaths = new Set();
+  for (const [index, command] of manifest.commands.entries()) {
+    const label = `${sourceLabel}.commands[${index}]`;
+    validateCLICommand(command, label, manifest.scope, seenPaths);
+  }
+}
+
+function validateCLICommand(command, label, scope, seenPaths) {
+  if (!command || typeof command !== "object") {
+    throw new Error(`${label} must be an object`);
+  }
+  if (!Array.isArray(command.path) || command.path.length === 0) {
+    throw new Error(`${label}.path must be a non-empty array`);
+  }
+  if (command.path[0] === scope) {
+    throw new Error(`${label}.path must not repeat scope`);
+  }
+  for (const [index, segment] of command.path.entries()) {
+    requireCLISegment(segment, `${label}.path[${index}]`);
+  }
+  const pathKey = command.path.join(".");
+  if (seenPaths.has(pathKey)) {
+    throw new Error(`${label}.path must be unique`);
+  }
+  seenPaths.add(pathKey);
+  requireNonEmpty(command.summary, `${label}.summary`);
+  validateCLIInputSchema(command.inputSchema, `${label}.inputSchema`);
+  validateCLIOutput(command.output, `${label}.output`);
+  validateCLIHandler(command.handler, `${label}.handler`);
+}
+
+function validateCLIInputSchema(schema, label) {
+  if (schema === undefined) {
+    return;
+  }
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (schema.type !== "object") {
+    throw new Error(`${label}.type must be object`);
+  }
+  if (
+    !schema.properties ||
+    typeof schema.properties !== "object" ||
+    Array.isArray(schema.properties)
+  ) {
+    throw new Error(`${label}.properties must be an object`);
+  }
+  for (const [name, property] of Object.entries(schema.properties)) {
+    requireCLISegment(name, `${label}.properties key`);
+    if (!property || typeof property !== "object" || Array.isArray(property)) {
+      throw new Error(`${label}.properties.${name} must be an object`);
+    }
+    if (!["string", "boolean", "integer"].includes(property.type)) {
+      throw new Error(
+        `${label}.properties.${name}.type must be string, boolean, or integer`
+      );
+    }
+    for (const key of Object.keys(property)) {
+      if (!["type", "description"].includes(key)) {
+        throw new Error(`${label}.properties.${name}.${key} is not supported`);
+      }
+    }
+  }
+  const required = schema.required ?? [];
+  if (!Array.isArray(required)) {
+    throw new Error(`${label}.required must be an array`);
+  }
+  for (const name of required) {
+    if (typeof name !== "string" || !Object.hasOwn(schema.properties, name)) {
+      throw new Error(
+        `${label}.required contains unknown property ${String(name)}`
+      );
+    }
+  }
+  for (const key of Object.keys(schema)) {
+    if (!["type", "properties", "required"].includes(key)) {
+      throw new Error(`${label}.${key} is not supported`);
+    }
+  }
+}
+
+function validateCLIOutput(output, label) {
+  if (!output || typeof output !== "object" || Array.isArray(output)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (!["json", "table"].includes(output.defaultMode)) {
+    throw new Error(`${label}.defaultMode must be json or table`);
+  }
+  if (output.defaultMode === "json" && output.json !== true) {
+    throw new Error(`${label}.json must be true when defaultMode is json`);
+  }
+  if (output.defaultMode === "table") {
+    if (
+      !output.table ||
+      !Array.isArray(output.table.columns) ||
+      output.table.columns.length === 0
+    ) {
+      throw new Error(
+        `${label}.table.columns must be a non-empty array when defaultMode is table`
+      );
+    }
+    for (const [index, column] of output.table.columns.entries()) {
+      requireCLISegment(column?.key, `${label}.table.columns[${index}].key`);
+      requireNonEmpty(column?.label, `${label}.table.columns[${index}].label`);
+    }
+  }
+}
+
+function validateCLIHandler(handler, label) {
+  if (!handler || typeof handler !== "object" || Array.isArray(handler)) {
+    throw new Error(`${label} must be an object`);
+  }
+  if (handler.kind !== "http") {
+    throw new Error(`${label}.kind must be http`);
+  }
+  if (handler.method !== "POST") {
+    throw new Error(`${label}.method must be POST`);
+  }
+  if (
+    typeof handler.path !== "string" ||
+    !handler.path.startsWith("/nextop/cli/")
+  ) {
+    throw new Error(`${label}.path must start with /nextop/cli/`);
+  }
+  const timeoutMs = handler.timeoutMs ?? 30000;
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 300000) {
+    throw new Error(`${label}.timeoutMs must be between 1000 and 300000`);
+  }
+}
+
+function requireCLISegment(value, label) {
+  const text = requireNonEmpty(value, label);
+  if (
+    !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(text) ||
+    text.startsWith("--")
+  ) {
+    throw new Error(
+      `${label} must contain lowercase letters, numbers, and hyphen only`
+    );
+  }
+  return text;
+}
+
+function validateLocalizationInfo(localizationInfo, sourceLabel) {
+  if (localizationInfo === undefined) {
+    return;
+  }
+  if (!localizationInfo || typeof localizationInfo !== "object") {
+    throw new Error(`${sourceLabel} localizationInfo must be an object`);
+  }
+
+  const defaultLocale = requireNonEmpty(
+    localizationInfo.defaultLocale,
+    `${sourceLabel}.localizationInfo.defaultLocale`
+  );
+  const seenLocales = new Set([defaultLocale.toLowerCase()]);
+  const additionalLocales = localizationInfo.additionalLocales ?? [];
+  if (!Array.isArray(additionalLocales)) {
+    throw new Error(
+      `${sourceLabel}.localizationInfo.additionalLocales must be an array`
+    );
+  }
+  for (const [index, entry] of additionalLocales.entries()) {
+    const label = `${sourceLabel}.localizationInfo.additionalLocales[${index}]`;
+    if (!entry || typeof entry !== "object") {
+      throw new Error(`${label} must be an object`);
+    }
+    const locale = requireNonEmpty(entry.locale, `${label}.locale`);
+    const localeKey = locale.toLowerCase();
+    if (seenLocales.has(localeKey)) {
+      throw new Error(`${label}.locale must be unique`);
+    }
+    seenLocales.add(localeKey);
+    const file = requireNonEmpty(entry.file, `${label}.file`);
+    if (!isRelativePackagePath(file)) {
+      throw new Error(`${label}.file must be a relative package path`);
+    }
+  }
+}
+
+export function releaseToCatalogApp(release) {
+  validateRelease(release);
+  return {
+    manifest: release.manifest,
+    distribution: {
+      kind: "remote",
+      artifactUrl: release.artifactUrl,
+      artifactSha256: release.artifactSha256,
+      iconUrl: release.iconUrl
+    }
+  };
+}
+
+export function validateRelease(release) {
+  if (!release || typeof release !== "object") {
+    throw new Error("release must be an object");
+  }
+  if (release.schemaVersion !== releaseSchemaVersion) {
+    throw new Error(`release schemaVersion must be ${releaseSchemaVersion}`);
+  }
+  for (const key of [
+    "appId",
+    "version",
+    "artifactUrl",
+    "artifactSha256",
+    "iconUrl"
+  ]) {
+    requireManifestString(release, key, "release");
+  }
+  validateManifest(release.manifest, "release.manifest");
+  if (release.manifest.appId !== release.appId) {
+    throw new Error("release manifest.appId must match release appId");
+  }
+  if (release.manifest.version !== release.version) {
+    throw new Error("release manifest.version must match release version");
+  }
+  if (!/^[a-f0-9]{64}$/i.test(release.artifactSha256)) {
+    throw new Error("release artifactSha256 must be a sha256 hex digest");
+  }
+  if (
+    !Number.isSafeInteger(release.artifactSizeBytes) ||
+    release.artifactSizeBytes <= 0
+  ) {
+    throw new Error("release artifactSizeBytes must be a positive integer");
+  }
+}
+
+function createZip(packageDir, artifactPath) {
+  const result = spawnSync("zip", ["-qr", artifactPath, "."], {
+    cwd: packageDir,
+    encoding: "utf8"
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `zip exited with status ${result.status}`);
+  }
+}
+
+async function fileDigestAndSize(filePath) {
+  const data = await readFile(filePath);
+  return {
+    sha256: createHash("sha256").update(data).digest("hex"),
+    size: data.length
+  };
+}
+
+async function requireFile(filePath) {
+  const fileStat = await stat(filePath).catch((error) => {
+    throw new Error(`required file missing: ${filePath}: ${error.message}`);
+  });
+  if (!fileStat.isFile()) {
+    throw new Error(`required path is not a file: ${filePath}`);
+  }
+  if (fileStat.size === 0) {
+    throw new Error(`required file is empty: ${filePath}`);
+  }
+}
+
+async function requireNonEmptyTextFile(filePath) {
+  const data = await readFile(filePath, "utf8").catch((error) => {
+    throw new Error(`required file missing: ${filePath}: ${error.message}`);
+  });
+  if (data.trim() === "") {
+    throw new Error(`required file is empty: ${filePath}`);
+  }
+}
+
+async function requireExecutableFile(filePath) {
+  const fileStat = await stat(filePath).catch((error) => {
+    throw new Error(`required file missing: ${filePath}: ${error.message}`);
+  });
+  if (!fileStat.isFile()) {
+    throw new Error(`required path is not a file: ${filePath}`);
+  }
+  if (fileStat.mode & 0o111) {
+    return;
+  }
+  throw new Error(`required file is not executable: ${filePath}`);
+}
+
+function requireManifestString(target, key, label) {
+  requireNonEmpty(target[key], `${label}.${key}`);
+}
+
+function requireNonEmpty(value, label) {
+  const text = String(value ?? "").trim();
+  if (text === "") {
+    throw new Error(`${label} is required`);
+  }
+  return text;
+}
+
+function requireSafePathSegment(value, label) {
+  if (!/^[A-Za-z0-9._+-]+$/.test(value)) {
+    throw new Error(
+      `${label} must use only letters, digits, dot, underscore, plus, or dash`
+    );
+  }
+}
+
+function isRelativePackagePath(value) {
+  const text = String(value ?? "").trim();
+  if (text === "" || path.isAbsolute(text) || text.startsWith("\\")) {
+    return false;
+  }
+  return !text.split(/[\\/]+/).includes("..");
+}
+
+function normalizeBaseUrl(value) {
+  return String(value).trim().replace(/\/+$/, "");
+}
+
+function joinURLPathSegments(...segments) {
+  return segments.map((segment) => encodeURLPathSegment(segment)).join("/");
+}
+
+function encodeURLPathSegment(value) {
+  return encodeURIComponent(String(value));
+}
+
+function resolveGitSha() {
+  const result = spawnSync("git", ["rev-parse", "HEAD"], {
+    encoding: "utf8"
+  });
+  if (result.status !== 0) {
+    return "";
+  }
+  return result.stdout.trim();
+}
+
+async function writeJson(filePath, value) {
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      throw new Error(`unexpected argument: ${arg}`);
+    }
+    const key = arg
+      .slice(2)
+      .replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+      throw new Error(`missing value for ${arg}`);
+    }
+    result[key] = value;
+    index += 1;
+  }
+  return result;
+}
+
+export async function main() {
+  const result = await buildNextopAppRelease(parseArgs(process.argv.slice(2)));
+  process.stdout.write(`${JSON.stringify(result.release, null, 2)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/bin/verify-nextop-app-release-artifacts.mjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { validateRelease } from "./build-nextop-app-release.mjs";
+
+const catalogSchemaVersion = "nextop.app.catalog.v1";
+
+export async function verifyNextopAppReleaseArtifacts(options) {
+  const releaseFiles = normalizeFiles(options.releaseFiles);
+  const catalogFile = options.catalogFile
+    ? path.resolve(String(options.catalogFile))
+    : null;
+  const verifyArtifacts = options.verifyArtifacts !== false;
+
+  if (releaseFiles.length === 0 && !catalogFile) {
+    throw new Error(
+      "at least one --release-file or --catalog-file is required"
+    );
+  }
+
+  const releases = [];
+  const releasesByAppID = new Map();
+  for (const releaseFile of releaseFiles) {
+    const release = JSON.parse(await readFile(releaseFile, "utf8"));
+    validateRelease(release);
+    if (releasesByAppID.has(release.appId)) {
+      throw new Error(`duplicate release appId ${release.appId}`);
+    }
+    releases.push(release);
+    releasesByAppID.set(release.appId, release);
+  }
+
+  const checks = [];
+  for (const release of releases) {
+    checks.push({
+      appId: release.appId,
+      artifactUrl: release.artifactUrl,
+      artifactSha256: release.artifactSha256,
+      artifactSizeBytes: release.artifactSizeBytes,
+      source: `release ${release.appId}`
+    });
+  }
+
+  if (catalogFile) {
+    const catalog = JSON.parse(await readFile(catalogFile, "utf8"));
+    validateCatalog(catalog);
+    const seenCatalogAppIDs = new Set();
+    for (const app of catalog.apps) {
+      const appId = app.manifest.appId;
+      if (seenCatalogAppIDs.has(appId)) {
+        throw new Error(`duplicate catalog appId ${appId}`);
+      }
+      seenCatalogAppIDs.add(appId);
+      const distribution = app.distribution;
+      if (!distribution || distribution.kind !== "remote") {
+        throw new Error(
+          `catalog app ${appId} distribution.kind must be remote`
+        );
+      }
+      for (const key of ["artifactUrl", "artifactSha256", "iconUrl"]) {
+        if (
+          typeof distribution[key] !== "string" ||
+          distribution[key].trim() === ""
+        ) {
+          throw new Error(
+            `catalog app ${appId} distribution.${key} is required`
+          );
+        }
+      }
+      requireSHA256Hex(
+        distribution.artifactSha256,
+        `catalog app ${appId} distribution.artifactSha256`
+      );
+
+      const release = releasesByAppID.get(appId);
+      if (release) {
+        assertCatalogMatchesRelease(app, release);
+      }
+
+      checks.push({
+        appId,
+        artifactUrl: distribution.artifactUrl,
+        artifactSha256: distribution.artifactSha256,
+        artifactSizeBytes: release?.artifactSizeBytes,
+        source: `catalog ${appId}`
+      });
+    }
+  }
+
+  if (verifyArtifacts) {
+    const artifactDigests = new Map();
+    for (const check of checks) {
+      let digest = artifactDigests.get(check.artifactUrl);
+      if (!digest) {
+        digest = await digestArtifact(check.artifactUrl);
+        artifactDigests.set(check.artifactUrl, digest);
+      }
+      if (digest.sha256 !== check.artifactSha256.toLowerCase()) {
+        throw new Error(
+          `${check.source} artifact sha256 mismatch: want ${check.artifactSha256} got ${digest.sha256}`
+        );
+      }
+      if (
+        Number.isSafeInteger(check.artifactSizeBytes) &&
+        digest.size !== check.artifactSizeBytes
+      ) {
+        throw new Error(
+          `${check.source} artifact size mismatch: want ${check.artifactSizeBytes} got ${digest.size}`
+        );
+      }
+    }
+  }
+
+  return {
+    catalogFile,
+    releaseFiles,
+    checkedArtifactCount: verifyArtifacts
+      ? new Set(checks.map((check) => check.artifactUrl)).size
+      : 0
+  };
+}
+
+function assertCatalogMatchesRelease(app, release) {
+  const appId = release.appId;
+  const distribution = app.distribution;
+  if (app.manifest.version !== release.version) {
+    throw new Error(
+      `catalog app ${appId} manifest.version must match release version`
+    );
+  }
+  if (distribution.artifactUrl !== release.artifactUrl) {
+    throw new Error(
+      `catalog app ${appId} artifactUrl must match latest release metadata`
+    );
+  }
+  if (distribution.artifactSha256 !== release.artifactSha256) {
+    throw new Error(
+      `catalog app ${appId} artifactSha256 must match latest release metadata`
+    );
+  }
+  if (distribution.iconUrl !== release.iconUrl) {
+    throw new Error(
+      `catalog app ${appId} iconUrl must match latest release metadata`
+    );
+  }
+}
+
+function validateCatalog(catalog) {
+  if (!catalog || typeof catalog !== "object") {
+    throw new Error("catalog must be an object");
+  }
+  if (catalog.schemaVersion !== catalogSchemaVersion) {
+    throw new Error(`catalog schemaVersion must be ${catalogSchemaVersion}`);
+  }
+  if (!Array.isArray(catalog.apps)) {
+    throw new Error("catalog apps must be an array");
+  }
+  for (const [index, app] of catalog.apps.entries()) {
+    if (!app || typeof app !== "object") {
+      throw new Error(`catalog apps[${index}] must be an object`);
+    }
+    if (
+      !app.manifest ||
+      typeof app.manifest !== "object" ||
+      typeof app.manifest.appId !== "string" ||
+      app.manifest.appId.trim() === ""
+    ) {
+      throw new Error(`catalog apps[${index}].manifest.appId is required`);
+    }
+  }
+}
+
+async function digestArtifact(artifactUrl) {
+  const url = String(artifactUrl).trim();
+  if (url.startsWith("http://") || url.startsWith("https://")) {
+    return digestHTTPArtifact(url);
+  }
+  if (url.startsWith("file://")) {
+    return digestFileArtifact(fileURLToPath(url));
+  }
+  return digestFileArtifact(path.resolve(url));
+}
+
+async function digestHTTPArtifact(url) {
+  let lastError;
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    try {
+      return await digestHTTPArtifactOnce(url);
+    } catch (error) {
+      lastError = error;
+      if (attempt < 3) {
+        await delay(1000 * attempt);
+      }
+    }
+  }
+  throw lastError;
+}
+
+async function digestHTTPArtifactOnce(url) {
+  const response = await fetch(url);
+  if (!response.ok || !response.body) {
+    throw new Error(
+      `download artifact failed: ${url}: HTTP ${response.status}`
+    );
+  }
+  const hash = createHash("sha256");
+  let size = 0;
+  for await (const chunk of response.body) {
+    const buffer = Buffer.from(chunk);
+    hash.update(buffer);
+    size += buffer.length;
+  }
+  return {
+    sha256: hash.digest("hex"),
+    size
+  };
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function digestFileArtifact(filePath) {
+  const hash = createHash("sha256");
+  let size = 0;
+  await new Promise((resolve, reject) => {
+    const stream = createReadStream(filePath);
+    stream.on("data", (chunk) => {
+      hash.update(chunk);
+      size += chunk.length;
+    });
+    stream.on("error", reject);
+    stream.on("end", resolve);
+  });
+  return {
+    sha256: hash.digest("hex"),
+    size
+  };
+}
+
+function normalizeFiles(value) {
+  const files = Array.isArray(value)
+    ? value
+    : String(value ?? "")
+        .split(/[\n,]/)
+        .map((file) => file.trim())
+        .filter(Boolean);
+  return files.map((file) => path.resolve(file));
+}
+
+function requireSHA256Hex(value, label) {
+  if (!/^[a-f0-9]{64}$/i.test(String(value ?? ""))) {
+    throw new Error(`${label} must be a sha256 hex digest`);
+  }
+}
+
+function parseArgs(argv) {
+  const result = {
+    releaseFiles: [],
+    verifyArtifacts: true
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--release-file") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("missing value for --release-file");
+      }
+      result.releaseFiles.push(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--catalog-file") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("missing value for --catalog-file");
+      }
+      result.catalogFile = value;
+      index += 1;
+      continue;
+    }
+    if (arg === "--skip-artifact-download") {
+      result.verifyArtifacts = false;
+      continue;
+    }
+    throw new Error(`unexpected argument: ${arg}`);
+  }
+  return result;
+}
+
+export async function main() {
+  const result = await verifyNextopAppReleaseArtifacts(
+    parseArgs(process.argv.slice(2))
+  );
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@tutti-os/app-release-tools",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "build-nextop-app-release": "./bin/build-nextop-app-release.mjs",
+    "build-nextop-app-catalog": "./bin/build-nextop-app-catalog.mjs",
+    "verify-nextop-app-release-artifacts": "./bin/verify-nextop-app-release-artifacts.mjs"
+  },
+  "exports": {
+    "./build-nextop-app-release": "./bin/build-nextop-app-release.mjs",
+    "./build-nextop-app-catalog": "./bin/build-nextop-app-catalog.mjs",
+    "./verify-nextop-app-release-artifacts": "./bin/verify-nextop-app-release-artifacts.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tutti-os/tutti.git",
+    "directory": "packages/workspace/app-release-tools"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"\"",
+    "test": "node --test ../../../tools/scripts/build-nextop-app-release.test.mjs"
+  }
+}