@tutti-os/app-release-tools 0.0.92 → 0.0.93

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

@@ -4,6 +4,7 @@ import { pathToFileURL } from "node:url";
 import path from "node:path";
 
 import {
+  normalizeRequiredTuttiCapabilities,
   releaseToCatalogApp,
   validateRelease
 } from "./build-tutti-app-release.mjs";
@@ -30,6 +31,7 @@ export async function buildTuttiAppCatalog(options) {
 
   const appsByID = new Map();
   const compatibilityByAppID = new Map();
+  const capabilityCompatibilityByAppID = new Map();
   if (existingCatalogPath) {
     const existingCatalog = JSON.parse(
       await readFile(existingCatalogPath, "utf8")
@@ -43,6 +45,11 @@ export async function buildTuttiAppCatalog(options) {
     )) {
       compatibilityByAppID.set(appId, entries);
     }
+    for (const [appId, entries] of Object.entries(
+      existingCatalog.compatibility?.capabilityApps ?? {}
+    )) {
+      capabilityCompatibilityByAppID.set(appId, entries);
+    }
   }
 
   const seenVersionsAppIDs = new Set();
@@ -53,7 +60,12 @@ export async function buildTuttiAppCatalog(options) {
       throw new Error(`duplicate versions appId ${versions.appId}`);
     }
     seenVersionsAppIDs.add(versions.appId);
-    applyVersionsDocument(appsByID, compatibilityByAppID, versions);
+    applyVersionsDocument(
+      appsByID,
+      compatibilityByAppID,
+      capabilityCompatibilityByAppID,
+      versions
+    );
   }
 
   const seenReleaseAppIDs = new Set();
@@ -72,7 +84,11 @@ export async function buildTuttiAppCatalog(options) {
     appsByID.set(release.appId, releaseToCatalogApp(release));
   }
 
-  if (appsByID.size === 0 && compatibilityByAppID.size === 0) {
+  if (
+    appsByID.size === 0 &&
+    compatibilityByAppID.size === 0 &&
+    capabilityCompatibilityByAppID.size === 0
+  ) {
     throw new Error(
       "at least one versions file, release file, or existing catalog app is required"
     );
@@ -86,11 +102,24 @@ export async function buildTuttiAppCatalog(options) {
       .filter(([, entries]) => entries.length > 0)
       .sort(([left], [right]) => left.localeCompare(right))
   );
+  const capabilityApps = Object.fromEntries(
+    [...capabilityCompatibilityByAppID.entries()]
+      .filter(([, entries]) => entries.length > 0)
+      .sort(([left], [right]) => left.localeCompare(right))
+  );
   const catalog = {
     schemaVersion: catalogSchemaVersion,
     apps,
-    ...(Object.keys(compatibilityApps).length > 0
-      ? { compatibility: { apps: compatibilityApps } }
+    ...(Object.keys(compatibilityApps).length > 0 ||
+    Object.keys(capabilityApps).length > 0
+      ? {
+          compatibility: {
+            apps: compatibilityApps,
+            ...(Object.keys(capabilityApps).length > 0
+              ? { capabilityApps }
+              : {})
+          }
+        }
       : {})
   };
   validateCatalog(catalog);
@@ -141,7 +170,18 @@ export function validateCatalog(catalog) {
   ) {
     throw new Error("catalog compatibility.apps must be an object");
   }
-  for (const [appId, entries] of Object.entries(compatibility.apps)) {
+  validateCatalogCompatibilityApps(compatibility.apps);
+  if (compatibility.capabilityApps !== undefined) {
+    validateCatalogCapabilityApps(
+      compatibility.capabilityApps,
+      seenLegacyAppIDs
+    );
+  }
+  return catalog;
+}
+
+function validateCatalogCompatibilityApps(compatibilityApps) {
+  for (const [appId, entries] of Object.entries(compatibilityApps)) {
     if (!Array.isArray(entries) || entries.length === 0) {
       throw new Error(`catalog compatibility app ${appId} must be non-empty`);
     }
@@ -169,7 +209,55 @@ export function validateCatalog(catalog) {
       seenVersions.add(version);
     }
   }
-  return catalog;
+}
+
+function validateCatalogCapabilityApps(capabilityApps, legacyAppIDs) {
+  if (
+    !capabilityApps ||
+    typeof capabilityApps !== "object" ||
+    Array.isArray(capabilityApps)
+  ) {
+    throw new Error("catalog compatibility.capabilityApps must be an object");
+  }
+  for (const [rawAppID, entries] of Object.entries(capabilityApps)) {
+    const appId = String(rawAppID).trim();
+    if (appId === "" || !Array.isArray(entries) || entries.length === 0) {
+      throw new Error(
+        `catalog capability compatibility app ${rawAppID} must be non-empty`
+      );
+    }
+    if (!legacyAppIDs.has(appId)) {
+      throw new Error(
+        `catalog capability compatibility app ${appId} requires a legacy fallback app`
+      );
+    }
+    const seenCapabilitySets = new Set();
+    const seenVersions = new Set();
+    for (const [index, entry] of entries.entries()) {
+      const label = `catalog capability compatibility app ${appId}[${index}]`;
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        throw new Error(`${label} must be an object`);
+      }
+      const requiredTuttiCapabilities = normalizeRequiredTuttiCapabilities(
+        entry.requiredTuttiCapabilities,
+        `${label}.requiredTuttiCapabilities`
+      );
+      const capabilityKey = requiredTuttiCapabilities.join("\u0000");
+      if (seenCapabilitySets.has(capabilityKey)) {
+        throw new Error(`${label} has duplicate requiredTuttiCapabilities`);
+      }
+      seenCapabilitySets.add(capabilityKey);
+      const entryAppID = validateCatalogApp(entry.app, `${label}.app`);
+      if (entryAppID !== appId) {
+        throw new Error(`${label}.app manifest.appId must match map key`);
+      }
+      const version = entry.app.manifest.version;
+      if (seenVersions.has(version)) {
+        throw new Error(`${label} has duplicate app version ${version}`);
+      }
+      seenVersions.add(version);
+    }
+  }
 }
 
 export function validateCatalogApp(app, label) {
@@ -200,7 +288,12 @@ export function validateCatalogApp(app, label) {
   return appId;
 }
 
-function applyVersionsDocument(appsByID, compatibilityByAppID, versions) {
+function applyVersionsDocument(
+  appsByID,
+  compatibilityByAppID,
+  capabilityCompatibilityByAppID,
+  versions
+) {
   const activeRecords = versions.versions.filter(
     (record) => record.status === "active"
   );
@@ -214,7 +307,9 @@ function applyVersionsDocument(appsByID, compatibilityByAppID, versions) {
     appsByID.delete(versions.appId);
   }
 
-  const entries = compatibilityFrontier(activeRecords).map((record) => ({
+  const entries = compatibilityFrontier(
+    activeRecords.filter((record) => record.minTuttiVersion !== undefined)
+  ).map((record) => ({
     minTuttiVersion: record.minTuttiVersion,
     app: releaseToCatalogApp(record.release)
   }));
@@ -223,6 +318,20 @@ function applyVersionsDocument(appsByID, compatibilityByAppID, versions) {
   } else {
     compatibilityByAppID.delete(versions.appId);
   }
+
+  const capabilityEntries = capabilityCompatibilityFrontier(
+    activeRecords.filter(
+      (record) => record.requiredTuttiCapabilities !== undefined
+    )
+  ).map((record) => ({
+    requiredTuttiCapabilities: record.requiredTuttiCapabilities,
+    app: releaseToCatalogApp(record.release)
+  }));
+  if (capabilityEntries.length > 0) {
+    capabilityCompatibilityByAppID.set(versions.appId, capabilityEntries);
+  } else {
+    capabilityCompatibilityByAppID.delete(versions.appId);
+  }
 }
 
 export function compatibilityFrontier(records) {
@@ -258,6 +367,27 @@ export function compatibilityFrontier(records) {
   return frontier;
 }
 
+export function capabilityCompatibilityFrontier(records) {
+  const highestByCapabilitySet = new Map();
+  for (const record of records) {
+    const capabilityKey = record.requiredTuttiCapabilities.join("\u0000");
+    const existing = highestByCapabilitySet.get(capabilityKey);
+    if (
+      !existing ||
+      compareReleaseVersions(record.release, existing.release) > 0
+    ) {
+      highestByCapabilitySet.set(capabilityKey, record);
+    }
+  }
+  return [...highestByCapabilitySet.values()].sort((left, right) => {
+    const leftKey = left.requiredTuttiCapabilities.join("\u0000");
+    const rightKey = right.requiredTuttiCapabilities.join("\u0000");
+    const keyComparison = leftKey.localeCompare(rightKey);
+    if (keyComparison !== 0) return keyComparison;
+    return compareReleaseVersions(left.release, right.release);
+  });
+}
+
 function highestReleaseRecord(records) {
   return [...records]
     .sort((left, right) => compareReleaseVersions(left.release, right.release))

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

@@ -167,9 +167,63 @@ export function validateManifest(manifest, sourceLabel = "manifest") {
   }
   validateManifestCLI(manifest.cli, sourceLabel);
   validateManifestReferences(manifest.references, sourceLabel);
+  requiredTuttiCapabilitiesForManifest(manifest, sourceLabel);
   validateLocalizationInfo(manifest.localizationInfo, sourceLabel);
 }
 
+export function requiredTuttiCapabilitiesForManifest(
+  manifest,
+  sourceLabel = "manifest"
+) {
+  const compatibility = manifest.hostCompatibility;
+  if (compatibility === undefined) return [];
+  if (
+    !compatibility ||
+    typeof compatibility !== "object" ||
+    Array.isArray(compatibility)
+  ) {
+    throw new Error(`${sourceLabel}.hostCompatibility must be an object`);
+  }
+  const unsupportedKey = Object.keys(compatibility).find(
+    (key) => key !== "requiredTuttiCapabilities"
+  );
+  if (unsupportedKey) {
+    throw new Error(
+      `${sourceLabel}.hostCompatibility.${unsupportedKey} is unsupported`
+    );
+  }
+  return normalizeRequiredTuttiCapabilities(
+    compatibility.requiredTuttiCapabilities,
+    `${sourceLabel}.hostCompatibility.requiredTuttiCapabilities`
+  );
+}
+
+export function normalizeRequiredTuttiCapabilities(value, label) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`${label} must be a non-empty array`);
+  }
+  if (value.length > 32) {
+    throw new Error(`${label} must contain at most 32 capabilities`);
+  }
+  const capabilities = value.map((capability, index) => {
+    if (typeof capability !== "string" || capability.trim() !== capability) {
+      throw new Error(`${label}[${index}] must be a normalized string`);
+    }
+    if (!/^[a-z][a-z0-9-]{0,63}$/u.test(capability)) {
+      throw new Error(`${label}[${index}] is invalid`);
+    }
+    return capability;
+  });
+  const normalized = [...new Set(capabilities)].sort();
+  if (
+    normalized.length !== capabilities.length ||
+    normalized.some((capability, index) => capability !== capabilities[index])
+  ) {
+    throw new Error(`${label} must be sorted and unique`);
+  }
+  return normalized;
+}
+
 function validateManifestCLI(cli, sourceLabel) {
   if (cli === undefined) {
     return;

package/bin/build-tutti-app-versions.mjs

@@ -3,7 +3,11 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import path from "node:path";
 
-import { validateRelease } from "./build-tutti-app-release.mjs";
+import {
+  normalizeRequiredTuttiCapabilities,
+  requiredTuttiCapabilitiesForManifest,
+  validateRelease
+} from "./build-tutti-app-release.mjs";
 import {
   compareReleaseVersions,
   requireSemver
@@ -40,16 +44,32 @@ export async function buildTuttiAppVersions(options) {
   }
 
   if (releaseFiles.length > 0) {
-    const minTuttiVersion = requireSemver(
-      options.minTuttiVersion,
-      "minTuttiVersion"
-    );
+    const minTuttiVersion = options.minTuttiVersion
+      ? requireSemver(options.minTuttiVersion, "minTuttiVersion")
+      : null;
     const status = normalizeStatus(options.status ?? "active");
     for (const releaseFile of releaseFiles) {
       const release = JSON.parse(await readFile(releaseFile, "utf8"));
       validateRelease(release);
+      const requiredTuttiCapabilities = requiredTuttiCapabilitiesForManifest(
+        release.manifest,
+        "release.manifest"
+      );
+      if (minTuttiVersion && requiredTuttiCapabilities.length > 0) {
+        throw new Error(
+          "a release cannot declare both minTuttiVersion and requiredTuttiCapabilities"
+        );
+      }
+      if (!minTuttiVersion && requiredTuttiCapabilities.length === 0) {
+        throw new Error(
+          "minTuttiVersion or release.manifest.hostCompatibility.requiredTuttiCapabilities is required"
+        );
+      }
       document = addVersionRecord(document, {
-        minTuttiVersion,
+        ...(minTuttiVersion ? { minTuttiVersion } : {}),
+        ...(requiredTuttiCapabilities.length > 0
+          ? { requiredTuttiCapabilities }
+          : {}),
         status,
         release
       });
@@ -104,10 +124,31 @@ export function validateVersionsDocument(document) {
     if (!record || typeof record !== "object" || Array.isArray(record)) {
       throw new Error(`${label} must be an object`);
     }
-    record.minTuttiVersion = requireSemver(
-      record.minTuttiVersion,
-      `${label}.minTuttiVersion`
-    );
+    const hasMinTuttiVersion = record.minTuttiVersion !== undefined;
+    const hasRequiredTuttiCapabilities =
+      record.requiredTuttiCapabilities !== undefined;
+    if (hasMinTuttiVersion && hasRequiredTuttiCapabilities) {
+      throw new Error(
+        `${label} cannot declare both minTuttiVersion and requiredTuttiCapabilities`
+      );
+    }
+    if (!hasMinTuttiVersion && !hasRequiredTuttiCapabilities) {
+      throw new Error(
+        `${label} must declare minTuttiVersion or requiredTuttiCapabilities`
+      );
+    }
+    if (hasMinTuttiVersion) {
+      record.minTuttiVersion = requireSemver(
+        record.minTuttiVersion,
+        `${label}.minTuttiVersion`
+      );
+    }
+    if (hasRequiredTuttiCapabilities) {
+      record.requiredTuttiCapabilities = normalizeRequiredTuttiCapabilities(
+        record.requiredTuttiCapabilities,
+        `${label}.requiredTuttiCapabilities`
+      );
+    }
     record.status = normalizeStatus(record.status);
     validateRelease(record.release);
     if (record.release.appId !== appId) {

package/bin/publish-tutti-app-metadata.mjs

@@ -7,6 +7,7 @@ import path from "node:path";
 
 import { buildTuttiAppCatalog } from "./build-tutti-app-catalog.mjs";
 import {
+  requiredTuttiCapabilitiesForManifest,
   releaseToCatalogApp,
   validateRelease
 } from "./build-tutti-app-release.mjs";
@@ -37,10 +38,6 @@ export async function publishTuttiAppMetadata(options) {
   if (!catalogOnly && !releasePath) {
     throw new Error("releasePath is required unless catalogOnly is true");
   }
-  if (!catalogOnly && !minTuttiVersion) {
-    throw new Error("minTuttiVersion is required for app releases");
-  }
-
   await mkdir(outputDir, { recursive: true });
   const release = releasePath
     ? JSON.parse(await readFile(releasePath, "utf8"))
@@ -51,6 +48,23 @@ export async function publishTuttiAppMetadata(options) {
       throw new Error("release appId must match input appId");
     }
   }
+  const requiredTuttiCapabilities = release
+    ? requiredTuttiCapabilitiesForManifest(release.manifest, "release.manifest")
+    : [];
+  if (
+    !catalogOnly &&
+    !minTuttiVersion &&
+    requiredTuttiCapabilities.length === 0
+  ) {
+    throw new Error(
+      "minTuttiVersion or release.manifest.hostCompatibility.requiredTuttiCapabilities is required for app releases"
+    );
+  }
+  if (minTuttiVersion && requiredTuttiCapabilities.length > 0) {
+    throw new Error(
+      "an app release cannot declare both minTuttiVersion and requiredTuttiCapabilities"
+    );
+  }
 
   const key = (suffix) => (prefix ? `${prefix}/${suffix}` : suffix);
   const versionsKey = key(`apps/${appId}/versions.json`);
@@ -78,7 +92,7 @@ export async function publishTuttiAppMetadata(options) {
 
       if (releasePath) {
         releaseFiles.push(releasePath);
-      } else if (!existingPath && minTuttiVersion) {
+      } else if (!existingPath) {
         const latest = await getObject({
           bucket,
           key: latestKey,
@@ -100,7 +114,9 @@ export async function publishTuttiAppMetadata(options) {
         existingVersionsPath: existingPath,
         baselineReleaseFiles,
         releaseFiles,
-        ...(releaseFiles.length > 0 ? { minTuttiVersion } : {}),
+        ...(releaseFiles.length > 0 && minTuttiVersion
+          ? { minTuttiVersion }
+          : {}),
         outputPath
       });
       return outputPath;
@@ -173,7 +189,10 @@ async function downloadLegacyBaseline(input) {
   });
   if (!catalog) return null;
   const document = JSON.parse(await readFile(catalog.path, "utf8"));
-  if ((document.compatibility?.apps?.[input.appId] ?? []).length > 0) {
+  if (
+    (document.compatibility?.apps?.[input.appId] ?? []).length > 0 ||
+    (document.compatibility?.capabilityApps?.[input.appId] ?? []).length > 0
+  ) {
     throw new Error(
       `versions index for ${input.appId} is missing but catalog compatibility history exists; restore versions.json before publishing`
     );

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

@@ -70,6 +70,18 @@ export async function verifyTuttiAppReleaseArtifacts(options) {
         );
       }
     }
+    for (const [appId, entries] of Object.entries(
+      catalog.compatibility?.capabilityApps ?? {}
+    )) {
+      for (const entry of entries) {
+        addCatalogAppCheck(
+          checks,
+          releasesByKey,
+          entry.app,
+          `catalog capability compatibility app ${appId}`
+        );
+      }
+    }
   }
 
   if (verifyArtifacts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tutti-os/app-release-tools",
-  "version": "0.0.92",
+  "version": "0.0.93",
   "private": false,
   "type": "module",
   "bin": {