源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s

This commit is contained in:
agent-radar committed 2026-09-01 20:17:27 +08:00
commit 2ed3415fb7
8018 files changed
+1936476

No files matched your search

@@ -0,0 +1,53 @@
# @tutti-os/app-release-tools
Command-line tools for publishing Tutti workspace apps into App Center release metadata.
## Commands
```sh
build-tutti-app-release --app-id vibe-design --package-dir dist/tutti-app/vibe-design --base-url https://cdn.example.test/tutti-app-releases
build-tutti-app-versions --release-file ./apps/vibe-design/0.2.0/release.json --min-tutti-version 0.12.0 --output ./apps/vibe-design/versions.json
build-tutti-app-catalog --versions-file ./apps/vibe-design/versions.json --output ./catalog.json
build-tutti-app-catalog --existing-catalog ./catalog.json --versions-file ./apps/vibe-design/versions.json --output ./catalog.json
verify-tutti-app-release-artifacts --release-file ./apps/vibe-design/latest.json
verify-tutti-app-release-artifacts --catalog-file ./catalog.json --versions-file ./apps/vibe-design/versions.json
```
The release command validates a complete Tutti app package, creates a
reproducible zip with stable entry ordering and timestamps, writes immutable
`release.json`, and writes mutable `latest.json`. Rebuilding the same package
version produces the same artifact SHA-256, so an interrupted release can
safely verify and reuse its immutable upload. When the manifest declares
`localizationInfo`, the release metadata includes the referenced manifest
locale files so App Center can localize uninstalled remote apps without
downloading the package.
App CLI manifests may declare `execution.mode: "wait"` for commands that block
until a run or session reaches a stop point. Wait commands use JSON output and
must leave `--timeout-ms` to the Tutti CLI as the optional total wait deadline;
App input schemas must not redefine it.
The versions command maintains one mutable `tutti.app.versions.v1` index per
app. Every catalog-eligible release has an explicit minimum Tutti version and
an `active` or `withdrawn` status. Reusing an immutable app version with changed
release or compatibility metadata is rejected.
The catalog command merges version indexes into `tutti.app.catalog.v1`.
`apps[]` contains the highest active app version whose minimum Tutti version is
`0.0.0`, so old Tutti clients remain safe. `compatibility.apps` contains only
the compact compatibility frontier needed by new Tutti clients, not every
historical release. Catalog output is rejected when it exceeds the legacy 1 MiB
reader limit. The older `--release-file` form remains available for legacy
tooling but does not create compatibility metadata.
The verify command checks release and catalog metadata against the referenced
artifact downloads. When `--catalog-file` is combined with `--release-file` or
`--versions-file`, catalog entries for those apps must exactly match the
corresponding release metadata before artifact SHA-256 and size checks run.
`publish-tutti-app-metadata` and `publish-tutti-app-catalog` update mutable S3
JSON objects with ETag conditional writes and retry on concurrent changes. They
bootstrap a missing versions index from the exact immutable release currently
present in the legacy catalog; they never infer legacy compatibility from a
newer `latest.json` object. Catalog publication validates all metadata and
downloads referenced artifacts before attempting the conditional S3 write.
@@ -0,0 +1,453 @@
#!/usr/bin/env node
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { pathToFileURL } from "node:url";
import path from "node:path";
import {
normalizeRequiredTuttiCapabilities,
releaseToCatalogApp,
validateRelease
} from "./build-tutti-app-release.mjs";
import { validateVersionsDocument } from "./build-tutti-app-versions.mjs";
import {
compareReleaseVersions,
compareSemver
} from "./tutti-app-versioning.mjs";
export const catalogSchemaVersion = "tutti.app.catalog.v1";
export const maxCatalogBytes = 1024 * 1024;
export async function buildTuttiAppCatalog(options) {
const existingCatalogPath = options.existingCatalogPath
? path.resolve(String(options.existingCatalogPath))
: null;
const releaseFiles = normalizeFiles(options.releaseFiles);
const versionsFiles = normalizeFiles(options.versionsFiles);
const outputPath = path.resolve(
options.outputPath
? String(options.outputPath)
: "dist/tutti-app-catalog/catalog.json"
);
const appsByID = new Map();
const compatibilityByAppID = new Map();
const capabilityCompatibilityByAppID = new Map();
if (existingCatalogPath) {
const existingCatalog = JSON.parse(
await readFile(existingCatalogPath, "utf8")
);
validateCatalog(existingCatalog);
for (const app of existingCatalog.apps) {
appsByID.set(app.manifest.appId, app);
}
for (const [appId, entries] of Object.entries(
existingCatalog.compatibility?.apps ?? {}
)) {
compatibilityByAppID.set(appId, entries);
}
for (const [appId, entries] of Object.entries(
existingCatalog.compatibility?.capabilityApps ?? {}
)) {
capabilityCompatibilityByAppID.set(appId, entries);
}
}
const seenVersionsAppIDs = new Set();
for (const versionsFile of versionsFiles) {
const versions = JSON.parse(await readFile(versionsFile, "utf8"));
validateVersionsDocument(versions);
if (seenVersionsAppIDs.has(versions.appId)) {
throw new Error(`duplicate versions appId ${versions.appId}`);
}
seenVersionsAppIDs.add(versions.appId);
applyVersionsDocument(
appsByID,
compatibilityByAppID,
capabilityCompatibilityByAppID,
versions
);
}
const seenReleaseAppIDs = new Set();
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}`);
}
if (seenVersionsAppIDs.has(release.appId)) {
throw new Error(
`appId ${release.appId} cannot be supplied as both release and versions metadata`
);
}
seenReleaseAppIDs.add(release.appId);
appsByID.set(release.appId, releaseToCatalogApp(release));
}
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"
);
}
const apps = [...appsByID.values()].sort((left, right) =>
left.manifest.appId.localeCompare(right.manifest.appId)
);
const compatibilityApps = Object.fromEntries(
[...compatibilityByAppID.entries()]
.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 ||
Object.keys(capabilityApps).length > 0
? {
compatibility: {
apps: compatibilityApps,
...(Object.keys(capabilityApps).length > 0
? { capabilityApps }
: {})
}
}
: {})
};
validateCatalog(catalog);
const encoded = `${JSON.stringify(catalog, null, 2)}\n`;
if (Buffer.byteLength(encoded) > maxCatalogBytes) {
throw new Error(
`catalog exceeds legacy ${maxCatalogBytes}-byte response limit`
);
}
await mkdir(path.dirname(outputPath), { recursive: true });
await writeFile(outputPath, encoded);
return { outputPath, catalog };
}
export function validateCatalog(catalog) {
if (!catalog || typeof catalog !== "object" || Array.isArray(catalog)) {
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");
}
const seenLegacyAppIDs = new Set();
for (const [index, app] of catalog.apps.entries()) {
const appId = validateCatalogApp(app, `catalog apps[${index}]`);
if (seenLegacyAppIDs.has(appId)) {
throw new Error(`duplicate catalog appId ${appId}`);
}
seenLegacyAppIDs.add(appId);
}
const compatibility = catalog.compatibility;
if (compatibility === undefined) {
return catalog;
}
if (
!compatibility ||
typeof compatibility !== "object" ||
Array.isArray(compatibility) ||
!compatibility.apps ||
typeof compatibility.apps !== "object" ||
Array.isArray(compatibility.apps)
) {
throw new Error("catalog compatibility.apps must be an object");
}
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`);
}
const seenVersions = new Set();
const seenMinimums = new Set();
for (const [index, entry] of entries.entries()) {
const label = `catalog compatibility app ${appId}[${index}]`;
if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
throw new Error(`${label} must be an object`);
}
const minTuttiVersion = String(entry.minTuttiVersion ?? "").trim();
compareSemver(minTuttiVersion, minTuttiVersion);
if (seenMinimums.has(minTuttiVersion)) {
throw new Error(`${label} has duplicate minTuttiVersion`);
}
seenMinimums.add(minTuttiVersion);
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);
}
}
}
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) {
if (!app || typeof app !== "object" || Array.isArray(app)) {
throw new Error(`${label} must be an object`);
}
const appId = String(app.manifest?.appId ?? "").trim();
const version = String(app.manifest?.version ?? "").trim();
if (!appId) {
throw new Error(`${label}.manifest.appId is required`);
}
compareSemver(version, version);
const distribution = app.distribution;
if (!distribution || distribution.kind !== "remote") {
throw new Error(`${label}.distribution.kind must be remote`);
}
for (const key of ["artifactUrl", "artifactSha256", "iconUrl"]) {
if (
typeof distribution[key] !== "string" ||
distribution[key].trim() === ""
) {
throw new Error(`${label}.distribution.${key} is required`);
}
}
if (!/^[a-f0-9]{64}$/iu.test(distribution.artifactSha256)) {
throw new Error(`${label}.distribution.artifactSha256 must be sha256`);
}
return appId;
}
function applyVersionsDocument(
appsByID,
compatibilityByAppID,
capabilityCompatibilityByAppID,
versions
) {
const activeRecords = versions.versions.filter(
(record) => record.status === "active"
);
const legacyRecords = activeRecords.filter(
(record) => record.minTuttiVersion === "0.0.0"
);
const legacy = highestReleaseRecord(legacyRecords);
if (legacy) {
appsByID.set(versions.appId, releaseToCatalogApp(legacy.release));
} else {
appsByID.delete(versions.appId);
}
const entries = compatibilityFrontier(
activeRecords.filter((record) => record.minTuttiVersion !== undefined)
).map((record) => ({
minTuttiVersion: record.minTuttiVersion,
app: releaseToCatalogApp(record.release)
}));
if (entries.length > 0) {
compatibilityByAppID.set(versions.appId, entries);
} 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) {
const highestByMinimum = new Map();
for (const record of records) {
const existing = highestByMinimum.get(record.minTuttiVersion);
if (
!existing ||
compareReleaseVersions(record.release, existing.release) > 0
) {
highestByMinimum.set(record.minTuttiVersion, record);
}
}
const candidates = [...highestByMinimum.values()].sort((left, right) => {
const minimum = compareSemver(left.minTuttiVersion, right.minTuttiVersion);
if (minimum !== 0) {
return minimum;
}
return compareReleaseVersions(left.release, right.release);
});
const frontier = [];
let highest = null;
for (const candidate of candidates) {
if (
!highest ||
compareReleaseVersions(candidate.release, highest.release) > 0
) {
frontier.push(candidate);
highest = candidate;
}
}
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))
.at(-1);
}
function normalizeFiles(value) {
const files = Array.isArray(value)
? value
: String(value ?? "")
.split(/[\n,]/u)
.map((file) => file.trim())
.filter(Boolean);
return files.map((file) => path.resolve(file));
}
function parseArgs(argv) {
const result = { releaseFiles: [], versionsFiles: [] };
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
const value = argv[index + 1];
if (
[
"--release-file",
"--versions-file",
"--existing-catalog",
"--output"
].includes(arg)
) {
if (!value || value.startsWith("--")) {
throw new Error(`missing value for ${arg}`);
}
if (arg === "--release-file") {
result.releaseFiles.push(value);
} else if (arg === "--versions-file") {
result.versionsFiles.push(value);
} else if (arg === "--existing-catalog") {
result.existingCatalogPath = value;
} else {
result.outputPath = value;
}
index += 1;
continue;
}
throw new Error(`unexpected argument: ${arg}`);
}
return result;
}
export async function main() {
const result = await buildTuttiAppCatalog(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;
});
}
@@ -0,0 +1,707 @@
#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { pathToFileURL } from "node:url";
import {
cp,
mkdir,
mkdtemp,
readFile,
readdir,
rm,
stat,
utimes,
writeFile
} from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { requireSemver } from "./tutti-app-versioning.mjs";
import { validateCLIManifest } from "./tutti-app-cli-manifest.mjs";
export { validateCLIManifest } from "./tutti-app-cli-manifest.mjs";
const manifestSchemaVersion = "tutti.app.manifest.v1";
const releaseSchemaVersion = "tutti.app.release.v1";
export async function buildTuttiAppRelease(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/tutti-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, "tutti.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");
requireSemver(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));
}
const localizations = await readManifestLocalizations(packageDir, manifest);
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);
await 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,
...(localizations.length > 0 ? { localizations } : {}),
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);
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;
}
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`
);
}
}
function validateManifestReferences(references, sourceLabel) {
if (references === undefined) {
return;
}
if (
!references ||
typeof references !== "object" ||
Array.isArray(references)
) {
throw new Error(`${sourceLabel} references must be an object`);
}
const unsupportedKey = Object.keys(references).find(
(key) => key !== "listEndpoint" && key !== "searchEndpoint"
);
if (unsupportedKey) {
throw new Error(
`${sourceLabel}.references.${unsupportedKey} is unsupported`
);
}
const listEndpoint = requireNonEmpty(
references.listEndpoint,
`${sourceLabel}.references.listEndpoint`
);
if (!isRelativeURLPath(listEndpoint)) {
throw new Error(
`${sourceLabel}.references.listEndpoint must be a relative URL path without query or fragment`
);
}
if (references.searchEndpoint !== undefined) {
const searchEndpoint = requireNonEmpty(
references.searchEndpoint,
`${sourceLabel}.references.searchEndpoint`
);
if (!isRelativeURLPath(searchEndpoint)) {
throw new Error(
`${sourceLabel}.references.searchEndpoint must be a relative URL path without query or fragment`
);
}
}
}
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 {
...(Array.isArray(release.localizations) && release.localizations.length > 0
? { localizations: release.localizations }
: {}),
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");
}
requireSemver(release.version, "release version");
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");
}
validateReleaseLocalizations(release.localizations, "release.localizations");
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");
}
}
async function readManifestLocalizations(packageDir, manifest) {
const localizations = [];
for (const entry of manifest.localizationInfo?.additionalLocales ?? []) {
const locale = requireNonEmpty(
entry.locale,
"manifest localization locale"
);
const filePath = path.join(packageDir, entry.file);
const document = await readLocalizationDocument(filePath);
const localization = normalizeLocalization(document, locale, filePath);
if (localization) {
localizations.push(localization);
}
}
return localizations;
}
function normalizeLocalization(document, locale, sourceLabel) {
if (!document || typeof document !== "object" || Array.isArray(document)) {
throw new Error(`${sourceLabel} must be a localization object`);
}
const localization = {
locale
};
if (document.name !== undefined) {
const name = requireOptionalString(document.name, `${sourceLabel}.name`);
if (name) {
localization.name = name;
}
}
if (document.description !== undefined) {
const description = requireOptionalString(
document.description,
`${sourceLabel}.description`
);
if (description) {
localization.description = description;
}
}
if (document.tags !== undefined) {
if (!Array.isArray(document.tags)) {
throw new Error(`${sourceLabel}.tags must be an array`);
}
const tags = document.tags
.map((tag, index) =>
requireOptionalString(tag, `${sourceLabel}.tags[${index}]`)
)
.filter(Boolean);
if (tags.length > 0) {
localization.tags = [...new Set(tags)];
}
}
if (!localization.name && !localization.description && !localization.tags) {
return null;
}
return localization;
}
async function readLocalizationDocument(filePath) {
try {
return JSON.parse(await readFile(filePath, "utf8"));
} catch (error) {
throw new Error(
`parse manifest localization file ${filePath}: ${error.message}`
);
}
}
function validateReleaseLocalizations(localizations, sourceLabel) {
if (localizations === undefined) {
return;
}
if (!Array.isArray(localizations)) {
throw new Error(`${sourceLabel} must be an array`);
}
const seenLocales = new Set();
for (const [index, localization] of localizations.entries()) {
const label = `${sourceLabel}[${index}]`;
if (!localization || typeof localization !== "object") {
throw new Error(`${label} must be an object`);
}
const locale = requireNonEmpty(localization.locale, `${label}.locale`);
const localeKey = locale.toLowerCase();
if (seenLocales.has(localeKey)) {
throw new Error(`${label}.locale must be unique`);
}
seenLocales.add(localeKey);
if (localization.name !== undefined) {
requireOptionalString(localization.name, `${label}.name`);
}
if (localization.description !== undefined) {
requireOptionalString(localization.description, `${label}.description`);
}
if (localization.tags !== undefined) {
if (!Array.isArray(localization.tags)) {
throw new Error(`${label}.tags must be an array`);
}
for (const [tagIndex, tag] of localization.tags.entries()) {
requireOptionalString(tag, `${label}.tags[${tagIndex}]`);
}
}
}
}
async function createZip(packageDir, artifactPath) {
const stagingDir = await mkdtemp(
path.join(tmpdir(), "tutti-app-release-archive-")
);
const archiveRoot = path.join(stagingDir, "package");
try {
await cp(packageDir, archiveRoot, {
recursive: true,
dereference: true
});
const entries = await normalizeArchiveEntries(archiveRoot);
await rm(artifactPath, { force: true });
const result = spawnSync("zip", ["-X", "-q", artifactPath, "-@"], {
cwd: archiveRoot,
encoding: "utf8",
env: {
...process.env,
LC_ALL: "C",
TZ: "UTC"
},
input: `${entries.join("\n")}\n`
});
if (result.error) {
throw result.error;
}
if (result.status !== 0) {
throw new Error(
result.stderr || `zip exited with status ${result.status}`
);
}
} finally {
await rm(stagingDir, { recursive: true, force: true });
}
}
async function normalizeArchiveEntries(rootDir, relativeDir = "") {
const fixedTimestamp = new Date("1980-01-01T00:00:00.000Z");
const directoryEntries = await readdir(path.join(rootDir, relativeDir), {
withFileTypes: true
});
directoryEntries.sort((left, right) =>
left.name < right.name ? -1 : left.name > right.name ? 1 : 0
);
const result = [];
for (const entry of directoryEntries) {
if (entry.name.includes("\n") || entry.name.includes("\r")) {
throw new Error(
`package path contains an unsupported newline: ${path.join(relativeDir, entry.name)}`
);
}
const relativePath = path.join(relativeDir, entry.name);
const absolutePath = path.join(rootDir, relativePath);
await utimes(absolutePath, fixedTimestamp, fixedTimestamp);
if (entry.isDirectory()) {
result.push(`${relativePath}/`);
result.push(...(await normalizeArchiveEntries(rootDir, relativePath)));
continue;
}
if (!entry.isFile()) {
throw new Error(`unsupported package entry type: ${relativePath}`);
}
result.push(relativePath);
}
return result;
}
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 requireOptionalString(value, label) {
if (typeof value !== "string") {
throw new Error(`${label} must be a string`);
}
return value.trim();
}
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 isRelativeURLPath(value) {
const text = String(value ?? "").trim();
if (
text === "" ||
!text.startsWith("/") ||
text.startsWith("//") ||
text.includes("\0")
) {
return false;
}
try {
const parsed = new URL(text, "http://tutti.local");
return (
parsed.origin === "http://tutti.local" &&
parsed.pathname === text &&
parsed.search === "" &&
parsed.hash === ""
);
} catch {
return false;
}
}
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 buildTuttiAppRelease(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;
});
}
@@ -0,0 +1,277 @@
#!/usr/bin/env node
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { pathToFileURL } from "node:url";
import path from "node:path";
import {
normalizeRequiredTuttiCapabilities,
requiredTuttiCapabilitiesForManifest,
validateRelease
} from "./build-tutti-app-release.mjs";
import {
compareReleaseVersions,
requireSemver
} from "./tutti-app-versioning.mjs";
export const versionsSchemaVersion = "tutti.app.versions.v1";
export async function buildTuttiAppVersions(options) {
const existingPath = options.existingVersionsPath
? path.resolve(String(options.existingVersionsPath))
: null;
const releaseFiles = normalizeFiles(options.releaseFiles);
const baselineReleaseFiles = normalizeFiles(options.baselineReleaseFiles);
const outputPath = path.resolve(
options.outputPath
? String(options.outputPath)
: "dist/tutti-app-release/versions.json"
);
let document = null;
if (existingPath) {
document = JSON.parse(await readFile(existingPath, "utf8"));
validateVersionsDocument(document);
}
for (const releaseFile of baselineReleaseFiles) {
const release = JSON.parse(await readFile(releaseFile, "utf8"));
validateRelease(release);
document = addVersionRecord(document, {
minTuttiVersion: "0.0.0",
status: "active",
release
});
}
if (releaseFiles.length > 0) {
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 } : {}),
...(requiredTuttiCapabilities.length > 0
? { requiredTuttiCapabilities }
: {}),
status,
release
});
}
}
if (options.setStatusVersion) {
if (!document) {
throw new Error("existing versions are required when setting status");
}
const version = requireSemver(options.setStatusVersion, "setStatusVersion");
const status = normalizeStatus(options.status);
const record = document.versions.find(
(candidate) => candidate.release.version === version
);
if (!record) {
throw new Error(`version ${version} is not present in versions index`);
}
record.status = status;
}
if (!document || document.versions.length === 0) {
throw new Error(
"at least one release, baseline release, or existing versions document is required"
);
}
document.versions.sort((left, right) =>
compareReleaseVersions(left.release, right.release)
);
validateVersionsDocument(document);
await mkdir(path.dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${JSON.stringify(document, null, 2)}\n`);
return { outputPath, versions: document };
}
export function validateVersionsDocument(document) {
if (!document || typeof document !== "object" || Array.isArray(document)) {
throw new Error("versions document must be an object");
}
if (document.schemaVersion !== versionsSchemaVersion) {
throw new Error(`versions schemaVersion must be ${versionsSchemaVersion}`);
}
const appId = requireNonEmpty(document.appId, "versions appId");
if (!Array.isArray(document.versions)) {
throw new Error("versions must be an array");
}
const seenVersions = new Set();
for (const [index, record] of document.versions.entries()) {
const label = `versions[${index}]`;
if (!record || typeof record !== "object" || Array.isArray(record)) {
throw new Error(`${label} must be an object`);
}
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) {
throw new Error(`${label}.release.appId must match versions appId`);
}
const version = requireSemver(
record.release.version,
`${label}.release.version`
);
if (seenVersions.has(version)) {
throw new Error(`duplicate versions release version ${version}`);
}
seenVersions.add(version);
}
return document;
}
function addVersionRecord(document, record) {
const appId = record.release.appId;
const result = document ?? {
schemaVersion: versionsSchemaVersion,
appId,
versions: []
};
validateVersionsDocument(result);
if (result.appId !== appId) {
throw new Error(
`release appId ${appId} must match versions appId ${result.appId}`
);
}
const existing = result.versions.find(
(candidate) => candidate.release.version === record.release.version
);
if (!existing) {
result.versions.push(record);
return result;
}
if (JSON.stringify(existing) !== JSON.stringify(record)) {
throw new Error(
`version ${record.release.version} already exists with different compatibility or release metadata`
);
}
return result;
}
function normalizeFiles(value) {
const files = Array.isArray(value)
? value
: String(value ?? "")
.split(/[\n,]/u)
.map((file) => file.trim())
.filter(Boolean);
return files.map((file) => path.resolve(file));
}
function normalizeStatus(value) {
const status = String(value ?? "").trim();
if (status !== "active" && status !== "withdrawn") {
throw new Error("status must be active or withdrawn");
}
return status;
}
function requireNonEmpty(value, label) {
if (typeof value !== "string" || value.trim() === "") {
throw new Error(`${label} is required`);
}
return value.trim();
}
function parseArgs(argv) {
const result = { releaseFiles: [], baselineReleaseFiles: [] };
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
const value = argv[index + 1];
if (
[
"--existing-versions",
"--release-file",
"--baseline-release-file",
"--min-tutti-version",
"--set-status-version",
"--status",
"--output"
].includes(arg)
) {
if (!value || value.startsWith("--")) {
throw new Error(`missing value for ${arg}`);
}
const key = {
"--existing-versions": "existingVersionsPath",
"--min-tutti-version": "minTuttiVersion",
"--set-status-version": "setStatusVersion",
"--status": "status",
"--output": "outputPath"
}[arg];
if (arg === "--release-file") {
result.releaseFiles.push(value);
} else if (arg === "--baseline-release-file") {
result.baselineReleaseFiles.push(value);
} else {
result[key] = value;
}
index += 1;
continue;
}
throw new Error(`unexpected argument: ${arg}`);
}
return result;
}
export async function main() {
const result = await buildTuttiAppVersions(parseArgs(process.argv.slice(2)));
process.stdout.write(`${JSON.stringify(result.versions, 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;
});
}
@@ -0,0 +1,70 @@
#!/usr/bin/env node
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 { compareReleaseVersions } from "./tutti-app-versioning.mjs";
export async function mergeTuttiAppLatest(options) {
const releasePath = path.resolve(String(options.releasePath));
const outputPath = path.resolve(String(options.outputPath));
const release = JSON.parse(await readFile(releasePath, "utf8"));
validateRelease(release);
let latest = release;
if (options.existingLatestPath) {
const existing = JSON.parse(
await readFile(path.resolve(String(options.existingLatestPath)), "utf8")
);
validateRelease(existing);
if (existing.appId !== release.appId) {
throw new Error("existing latest appId must match release appId");
}
if (compareReleaseVersions(existing, release) > 0) {
latest = existing;
}
}
await mkdir(path.dirname(outputPath), { recursive: true });
await writeFile(outputPath, `${JSON.stringify(latest, null, 2)}\n`);
return { outputPath, latest };
}
function parseArgs(argv) {
const result = {};
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
const value = argv[index + 1];
if (["--release-file", "--existing-latest", "--output"].includes(arg)) {
if (!value || value.startsWith("--")) {
throw new Error(`missing value for ${arg}`);
}
if (arg === "--release-file") result.releasePath = value;
if (arg === "--existing-latest") result.existingLatestPath = value;
if (arg === "--output") result.outputPath = value;
index += 1;
continue;
}
throw new Error(`unexpected argument: ${arg}`);
}
if (!result.releasePath || !result.outputPath) {
throw new Error("--release-file and --output are required");
}
return result;
}
export async function main() {
const result = await mergeTuttiAppLatest(parseArgs(process.argv.slice(2)));
process.stdout.write(`${JSON.stringify(result.latest, 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;
});
}
@@ -0,0 +1,199 @@
#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import { copyFile, mkdir } from "node:fs/promises";
import { pathToFileURL } from "node:url";
import path from "node:path";
import { buildTuttiAppCatalog } from "./build-tutti-app-catalog.mjs";
import { publishTuttiAppMetadata } from "./publish-tutti-app-metadata.mjs";
import { verifyTuttiAppReleaseArtifacts } from "./verify-tutti-app-release-artifacts.mjs";
export async function publishTuttiAppCatalog(options) {
const appIds = [...new Set(options.appIds ?? [])]
.map((value) => String(value).trim())
.filter(Boolean)
.sort();
if (appIds.length === 0) throw new Error("at least one appId is required");
const bucket = requireNonEmpty(options.s3Bucket, "s3Bucket");
const prefix = String(options.s3Prefix ?? "")
.trim()
.replace(/^\/+|\/+$/gu, "");
const mode = options.mode ?? "merge";
if (mode !== "merge" && mode !== "replace") {
throw new Error("mode must be merge or replace");
}
const outputDir = path.resolve(
String(options.outputDir ?? "tutti-app-catalog")
);
await mkdir(outputDir, { recursive: true });
const key = (suffix) => (prefix ? `${prefix}/${suffix}` : suffix);
const catalogKey = key("catalog.json");
let lastError = null;
for (let attempt = 1; attempt <= 3; attempt += 1) {
const attemptDir = path.join(outputDir, `attempt-${attempt}`);
await mkdir(attemptDir, { recursive: true });
const existing = await getObject({
bucket,
key: catalogKey,
outputPath: path.join(attemptDir, "existing-catalog.json"),
required: false
});
const versionsFiles = [];
for (const appId of appIds) {
let versions = await getObject({
bucket,
key: key(`apps/${appId}/versions.json`),
outputPath: path.join(attemptDir, `${appId}-versions.json`),
required: false
});
if (!versions) {
await publishTuttiAppMetadata({
appId,
s3Bucket: bucket,
s3Prefix: prefix,
catalogOnly: true,
publishCatalog: false,
outputDir: path.join(attemptDir, `${appId}-bootstrap`)
});
versions = await getObject({
bucket,
key: key(`apps/${appId}/versions.json`),
outputPath: path.join(attemptDir, `${appId}-versions.json`),
required: true
});
}
versionsFiles.push(versions.path);
}
const catalogPath = path.join(attemptDir, "catalog.json");
await buildTuttiAppCatalog({
existingCatalogPath: mode === "merge" ? existing?.path : null,
versionsFiles,
outputPath: catalogPath
});
await verifyTuttiAppReleaseArtifacts({
catalogFile: catalogPath,
versionsFiles,
verifyArtifacts: true
});
try {
putObject({
bucket,
key: catalogKey,
path: catalogPath,
etag: existing?.etag ?? null
});
const stablePath = path.join(outputDir, "catalog.json");
await copyFile(catalogPath, stablePath);
return { catalogPath: stablePath, appIds, mode };
} catch (error) {
if (!/(?:412|PreconditionFailed|precondition)/iu.test(error.message)) {
throw error;
}
lastError = error;
}
}
throw new Error(
`catalog changed concurrently: ${lastError?.message ?? "failed"}`
);
}
async function getObject({ bucket, key, outputPath, required }) {
const head = runAWS(
["s3api", "head-object", "--bucket", bucket, "--key", key],
{ allowMissing: !required }
);
if (head.missing) return null;
const metadata = JSON.parse(head.stdout);
runAWS(["s3api", "get-object", "--bucket", bucket, "--key", key, outputPath]);
return { path: outputPath, etag: metadata.ETag };
}
function putObject({ bucket, key, path: filePath, etag }) {
const args = [
"s3api",
"put-object",
"--bucket",
bucket,
"--key",
key,
"--body",
filePath,
"--content-type",
"application/json",
"--cache-control",
"public, max-age=60",
...(etag ? ["--if-match", etag] : ["--if-none-match", "*"])
];
runAWS(args);
}
function runAWS(args, options = {}) {
const result = spawnSync("aws", args, {
encoding: "utf8",
maxBuffer: 10 * 1024 * 1024
});
if (result.status === 0) {
return { stdout: result.stdout, missing: false };
}
const message = `${result.stderr ?? ""}\n${result.stdout ?? ""}`.trim();
if (
options.allowMissing &&
/(?:404|Not Found|NoSuchKey|NotFound)/iu.test(message)
) {
return { stdout: "", missing: true };
}
throw new Error(`aws ${args.slice(0, 2).join(" ")} failed: ${message}`);
}
function requireNonEmpty(value, label) {
const text = String(value ?? "").trim();
if (!text) throw new Error(`${label} is required`);
return text;
}
function parseArgs(argv) {
const result = { appIds: [] };
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
const value = argv[index + 1];
if (
[
"--app-id",
"--s3-bucket",
"--s3-prefix",
"--mode",
"--output-dir"
].includes(arg)
) {
if (value === undefined || value.startsWith("--")) {
throw new Error(`missing value for ${arg}`);
}
if (arg === "--app-id") result.appIds.push(value);
if (arg === "--s3-bucket") result.s3Bucket = value;
if (arg === "--s3-prefix") result.s3Prefix = value;
if (arg === "--mode") result.mode = value;
if (arg === "--output-dir") result.outputDir = value;
index += 1;
continue;
}
throw new Error(`unexpected argument: ${arg}`);
}
return result;
}
export async function main() {
const result = await publishTuttiAppCatalog(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;
});
}
@@ -0,0 +1,384 @@
#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import { copyFile, mkdir, readFile } from "node:fs/promises";
import { pathToFileURL } from "node:url";
import { isDeepStrictEqual } from "node:util";
import path from "node:path";
import { buildTuttiAppCatalog } from "./build-tutti-app-catalog.mjs";
import {
requiredTuttiCapabilitiesForManifest,
releaseToCatalogApp,
validateRelease
} from "./build-tutti-app-release.mjs";
import { buildTuttiAppVersions } from "./build-tutti-app-versions.mjs";
import { mergeTuttiAppLatest } from "./merge-tutti-app-latest.mjs";
import { requireSemver } from "./tutti-app-versioning.mjs";
const maxCASAttempts = 3;
export async function publishTuttiAppMetadata(options) {
const appId = requireNonEmpty(options.appId, "appId");
const bucket = requireNonEmpty(options.s3Bucket, "s3Bucket");
const prefix = String(options.s3Prefix ?? "")
.trim()
.replace(/^\/+|\/+$/gu, "");
const outputDir = path.resolve(
String(options.outputDir ?? "tutti-app-metadata")
);
const publishCatalog = options.publishCatalog === true;
const catalogOnly = options.catalogOnly === true;
const releasePath = options.releasePath
? path.resolve(String(options.releasePath))
: null;
const minTuttiVersion = options.minTuttiVersion
? requireSemver(options.minTuttiVersion, "minTuttiVersion")
: null;
if (!catalogOnly && !releasePath) {
throw new Error("releasePath is required unless catalogOnly is true");
}
await mkdir(outputDir, { recursive: true });
const release = releasePath
? JSON.parse(await readFile(releasePath, "utf8"))
: null;
if (release) {
validateRelease(release);
if (release.appId !== appId) {
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`);
const latestKey = key(`apps/${appId}/latest.json`);
const catalogKey = key("catalog.json");
const versionsPath = await updateJSONWithCAS({
bucket,
key: versionsKey,
outputDir,
label: "versions",
build: async ({ existingPath, attemptDir }) => {
const baselineReleaseFiles = [];
const releaseFiles = [];
if (!existingPath) {
const baseline = await downloadLegacyBaseline({
appId,
bucket,
catalogKey,
key,
outputDir: attemptDir
});
if (baseline) baselineReleaseFiles.push(baseline);
}
if (releasePath) {
releaseFiles.push(releasePath);
} else if (!existingPath) {
const latest = await getObject({
bucket,
key: latestKey,
outputPath: path.join(attemptDir, "latest.json"),
required: true
});
const latestRelease = JSON.parse(await readFile(latest.path, "utf8"));
validateRelease(latestRelease);
const baselineVersion = baselineReleaseFiles.length
? JSON.parse(await readFile(baselineReleaseFiles[0], "utf8")).version
: null;
if (latestRelease.version !== baselineVersion) {
releaseFiles.push(latest.path);
}
}
const outputPath = path.join(attemptDir, "versions.json");
await buildTuttiAppVersions({
existingVersionsPath: existingPath,
baselineReleaseFiles,
releaseFiles,
...(releaseFiles.length > 0 && minTuttiVersion
? { minTuttiVersion }
: {}),
outputPath
});
return outputPath;
}
});
let latestPath = null;
if (releasePath) {
latestPath = await updateJSONWithCAS({
bucket,
key: latestKey,
outputDir,
label: "latest",
build: async ({ existingPath, attemptDir }) => {
const outputPath = path.join(attemptDir, "latest.json");
await mergeTuttiAppLatest({
releasePath,
existingLatestPath: existingPath,
outputPath
});
return outputPath;
}
});
}
let catalogPath = null;
if (publishCatalog) {
catalogPath = await updateJSONWithCAS({
bucket,
key: catalogKey,
outputDir,
label: "catalog",
build: async ({ existingPath, attemptDir }) => {
const outputPath = path.join(attemptDir, "catalog.json");
await buildTuttiAppCatalog({
existingCatalogPath: existingPath,
versionsFiles: [versionsPath],
outputPath
});
return outputPath;
}
});
}
const stableVersionsPath = path.join(outputDir, "versions.json");
await copyFile(versionsPath, stableVersionsPath);
const stableLatestPath = latestPath
? path.join(outputDir, "latest.json")
: null;
if (latestPath) await copyFile(latestPath, stableLatestPath);
const stableCatalogPath = catalogPath
? path.join(outputDir, "catalog.json")
: null;
if (catalogPath) await copyFile(catalogPath, stableCatalogPath);
return {
appId,
versionsPath: stableVersionsPath,
latestPath: stableLatestPath,
catalogPath: stableCatalogPath
};
}
async function downloadLegacyBaseline(input) {
const catalog = await getObject({
bucket: input.bucket,
key: input.catalogKey,
outputPath: path.join(input.outputDir, "existing-catalog.json"),
required: false
});
if (!catalog) return null;
const document = JSON.parse(await readFile(catalog.path, "utf8"));
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`
);
}
const app = document.apps?.find(
(candidate) => candidate?.manifest?.appId === input.appId
);
const version = app?.manifest?.version;
if (typeof version !== "string" || version.trim() === "") return null;
const baseline = await getObject({
bucket: input.bucket,
key: input.key(`apps/${input.appId}/${version}/release.json`),
outputPath: path.join(input.outputDir, "baseline-release.json"),
required: true
});
const release = JSON.parse(await readFile(baseline.path, "utf8"));
validateRelease(release);
if (release.appId !== input.appId || release.version !== version) {
throw new Error("legacy baseline release does not match catalog app");
}
if (!isDeepStrictEqual(releaseToCatalogApp(release), app)) {
throw new Error(
"legacy baseline release projection does not match catalog app"
);
}
return baseline.path;
}
async function updateJSONWithCAS(input) {
let lastPreconditionError = null;
for (let attempt = 1; attempt <= maxCASAttempts; attempt += 1) {
const attemptDir = path.join(input.outputDir, `${input.label}-${attempt}`);
await mkdir(attemptDir, { recursive: true });
const existing = await getObject({
bucket: input.bucket,
key: input.key,
outputPath: path.join(attemptDir, "existing.json"),
required: false
});
const outputPath = await input.build({
existingPath: existing?.path ?? null,
attemptDir
});
try {
putObject({
bucket: input.bucket,
key: input.key,
path: outputPath,
etag: existing?.etag ?? null
});
return outputPath;
} catch (error) {
if (!isPreconditionFailure(error)) throw error;
lastPreconditionError = error;
}
}
throw new Error(
`${input.label} metadata changed concurrently after ${maxCASAttempts} attempts: ${lastPreconditionError?.message ?? "precondition failed"}`
);
}
async function getObject({ bucket, key, outputPath, required }) {
const head = runAWS(
["s3api", "head-object", "--bucket", bucket, "--key", key],
{ allowMissing: !required }
);
if (head.missing) return null;
const metadata = JSON.parse(head.stdout);
runAWS(["s3api", "get-object", "--bucket", bucket, "--key", key, outputPath]);
return { path: outputPath, etag: metadata.ETag };
}
function putObject({ bucket, key, path: filePath, etag }) {
const args = [
"s3api",
"put-object",
"--bucket",
bucket,
"--key",
key,
"--body",
filePath,
"--content-type",
"application/json",
"--cache-control",
"public, max-age=60"
];
if (etag) {
args.push("--if-match", etag);
} else {
args.push("--if-none-match", "*");
}
runAWS(args);
}
function runAWS(args, options = {}) {
const result = spawnSync("aws", args, {
encoding: "utf8",
maxBuffer: 10 * 1024 * 1024
});
if (result.status === 0) {
return { stdout: result.stdout, missing: false };
}
const message = `${result.stderr ?? ""}\n${result.stdout ?? ""}`.trim();
if (
options.allowMissing &&
/(?:404|Not Found|NoSuchKey|NotFound)/iu.test(message)
) {
return { stdout: "", missing: true };
}
const error = new Error(
`aws ${args.slice(0, 2).join(" ")} failed: ${message}`
);
error.awsOutput = message;
throw error;
}
function isPreconditionFailure(error) {
return /(?:412|PreconditionFailed|precondition)/iu.test(
error?.awsOutput ?? error?.message ?? ""
);
}
function requireNonEmpty(value, label) {
const text = String(value ?? "").trim();
if (!text) throw new Error(`${label} is required`);
return text;
}
function parseArgs(argv) {
const result = {};
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
if (arg === "--publish-catalog") {
result.publishCatalog = true;
continue;
}
if (arg === "--catalog-only") {
result.catalogOnly = true;
continue;
}
const value = argv[index + 1];
if (
[
"--app-id",
"--s3-bucket",
"--s3-prefix",
"--release-file",
"--min-tutti-version",
"--output-dir"
].includes(arg)
) {
if (value === undefined || value.startsWith("--")) {
throw new Error(`missing value for ${arg}`);
}
const key = {
"--app-id": "appId",
"--s3-bucket": "s3Bucket",
"--s3-prefix": "s3Prefix",
"--release-file": "releasePath",
"--min-tutti-version": "minTuttiVersion",
"--output-dir": "outputDir"
}[arg];
result[key] = value;
index += 1;
continue;
}
throw new Error(`unexpected argument: ${arg}`);
}
return result;
}
export async function main() {
const result = await publishTuttiAppMetadata(
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;
});
}
@@ -0,0 +1,247 @@
const cliManifestSchemaVersion = "tutti.app.cli.v1";
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`);
validateCLIVisibility(command.visibility, `${label}.visibility`);
validateCLIInputSchema(command.inputSchema, `${label}.inputSchema`);
validateCLIOutput(command.output, `${label}.output`);
validateCLIExecution(
command.execution,
command.inputSchema,
command.output,
`${label}.execution`
);
validateCLIHandler(command.handler, `${label}.handler`);
}
function validateCLIVisibility(visibility, label) {
if (visibility === undefined) {
return;
}
if (!["public", "integration"].includes(visibility)) {
throw new Error(`${label} must be public or integration`);
}
}
function validateCLIExecution(execution, inputSchema, output, label) {
if (execution === undefined) {
return;
}
if (!execution || typeof execution !== "object" || Array.isArray(execution)) {
throw new Error(`${label} must be an object`);
}
if (execution.mode !== "wait") {
throw new Error(`${label}.mode must be wait`);
}
if (output?.defaultMode !== "json" || output?.json !== true) {
throw new Error(`${label} mode wait requires json default output`);
}
if (inputSchema?.properties?.["timeout-ms"] !== undefined) {
throw new Error(
`${label} mode wait reserves --timeout-ms for the total CLI wait timeout`
);
}
}
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`
);
}
validateCLIInputEnum(
property.enum,
property.type,
`${label}.properties.${name}.enum`
);
validateCLIInputDefault(
property.default,
property.type,
property.enum,
`${label}.properties.${name}.default`
);
for (const key of Object.keys(property)) {
if (!["type", "description", "enum", "default"].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 validateCLIInputDefault(value, type, enumValues, label) {
if (value === undefined) {
return;
}
validateCLIInputValue(value, type, label);
if (enumValues !== undefined && !enumValues.includes(value)) {
throw new Error(`${label} must be one of the declared enum values`);
}
}
function validateCLIInputEnum(values, type, label) {
if (values === undefined) {
return;
}
if (!Array.isArray(values) || values.length === 0) {
throw new Error(`${label} must be a non-empty array`);
}
for (const [index, value] of values.entries()) {
validateCLIInputValue(value, type, `${label}[${index}]`);
}
}
function validateCLIInputValue(value, type, label) {
if (type === "integer") {
if (!Number.isInteger(value)) {
throw new Error(`${label} must be an integer`);
}
return;
}
if (typeof value !== type) {
throw new Error(`${label} must be ${type}`);
}
}
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("/tutti/cli/")
) {
throw new Error(`${label}.path must start with /tutti/cli/`);
}
const timeoutMs = handler.timeoutMs ?? 30000;
if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) {
throw new Error(`${label}.timeoutMs must be between 1000 and 600000`);
}
}
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 requireNonEmpty(value, label) {
const text = String(value ?? "").trim();
if (!text) {
throw new Error(`${label} is required`);
}
return text;
}
@@ -0,0 +1,44 @@
import semver from "semver";
export function requireSemver(value, label, options = {}) {
const text = String(value ?? "").trim();
const normalized = options.allowLeadingV ? text.replace(/^v/u, "") : text;
if (!normalized || semver.valid(normalized) === null) {
throw new Error(`${label} must be valid SemVer`);
}
return normalized;
}
export function compareSemver(left, right) {
return semver.compare(
requireSemver(left, "left version", { allowLeadingV: true }),
requireSemver(right, "right version", { allowLeadingV: true })
);
}
export function compareReleaseVersions(left, right) {
const precedence = compareSemver(left.version, right.version);
if (precedence !== 0) {
return precedence;
}
const publishedAt = comparePublishedAt(left.publishedAt, right.publishedAt);
if (publishedAt !== 0) {
return publishedAt;
}
return left.version.localeCompare(right.version);
}
export function isTuttiVersionCompatible(minTuttiVersion, tuttiVersion) {
return compareSemver(minTuttiVersion, tuttiVersion) <= 0;
}
function comparePublishedAt(left, right) {
const leftTime = Date.parse(String(left ?? ""));
const rightTime = Date.parse(String(right ?? ""));
if (Number.isNaN(leftTime) || Number.isNaN(rightTime)) {
return String(left ?? "").localeCompare(String(right ?? ""));
}
return leftTime - rightTime;
}
@@ -0,0 +1,302 @@
#!/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 {
validateCatalog,
validateCatalogApp
} from "./build-tutti-app-catalog.mjs";
import { validateRelease } from "./build-tutti-app-release.mjs";
import { validateVersionsDocument } from "./build-tutti-app-versions.mjs";
export async function verifyTuttiAppReleaseArtifacts(options) {
const releaseFiles = normalizeFiles(options.releaseFiles);
const versionsFiles = normalizeFiles(options.versionsFiles);
const catalogFile = options.catalogFile
? path.resolve(String(options.catalogFile))
: null;
const verifyArtifacts = options.verifyArtifacts !== false;
if (releaseFiles.length === 0 && versionsFiles.length === 0 && !catalogFile) {
throw new Error(
"at least one --release-file, --versions-file, or --catalog-file is required"
);
}
const releasesByKey = new Map();
for (const versionsFile of versionsFiles) {
const document = JSON.parse(await readFile(versionsFile, "utf8"));
validateVersionsDocument(document);
for (const record of document.versions) {
const key = releaseKey(record.release.appId, record.release.version);
if (releasesByKey.has(key)) {
throw new Error(`duplicate versions release ${key}`);
}
releasesByKey.set(key, record.release);
}
}
const checks = new Map();
for (const releaseFile of releaseFiles) {
const release = JSON.parse(await readFile(releaseFile, "utf8"));
validateRelease(release);
const key = releaseKey(release.appId, release.version);
const existing = releasesByKey.get(key);
if (existing && JSON.stringify(existing) !== JSON.stringify(release)) {
throw new Error(`release ${key} does not match versions metadata`);
}
releasesByKey.set(key, release);
addArtifactCheck(checks, release, `release ${key}`);
}
if (catalogFile) {
const catalog = JSON.parse(await readFile(catalogFile, "utf8"));
validateCatalog(catalog);
for (const app of catalog.apps) {
addCatalogAppCheck(checks, releasesByKey, app, "catalog legacy app");
}
for (const [appId, entries] of Object.entries(
catalog.compatibility?.apps ?? {}
)) {
for (const entry of entries) {
addCatalogAppCheck(
checks,
releasesByKey,
entry.app,
`catalog compatibility app ${appId}`
);
}
}
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) {
for (const check of checks.values()) {
const digest = await digestArtifact(check.artifactUrl);
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,
versionsFiles,
checkedArtifactCount: verifyArtifacts ? checks.size : 0
};
}
function addCatalogAppCheck(checks, releasesByKey, app, source) {
const appId = validateCatalogApp(app, source);
const version = app.manifest.version;
const release = releasesByKey.get(releaseKey(appId, version));
if (release) assertCatalogMatchesRelease(app, release);
addArtifactCheck(
checks,
{
appId,
version,
artifactUrl: app.distribution.artifactUrl,
artifactSha256: app.distribution.artifactSha256,
artifactSizeBytes: release?.artifactSizeBytes
},
`${source} ${appId}@${version}`
);
}
function addArtifactCheck(checks, release, source) {
const existing = checks.get(release.artifactUrl);
const check = {
artifactUrl: release.artifactUrl,
artifactSha256: release.artifactSha256,
artifactSizeBytes: release.artifactSizeBytes,
source
};
if (
existing &&
(existing.artifactSha256 !== check.artifactSha256 ||
(Number.isSafeInteger(existing.artifactSizeBytes) &&
Number.isSafeInteger(check.artifactSizeBytes) &&
existing.artifactSizeBytes !== check.artifactSizeBytes))
) {
throw new Error(`artifact metadata conflicts for ${release.artifactUrl}`);
}
checks.set(release.artifactUrl, existing ?? check);
}
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`
);
}
if (
JSON.stringify(app.localizations ?? []) !==
JSON.stringify(release.localizations ?? [])
) {
throw new Error(
`catalog app ${appId} localizations must match latest release metadata`
);
}
}
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,]/u)
.map((file) => file.trim())
.filter(Boolean);
return files.map((file) => path.resolve(file));
}
function releaseKey(appId, version) {
return `${appId}@${version}`;
}
function parseArgs(argv) {
const result = {
releaseFiles: [],
versionsFiles: [],
verifyArtifacts: true
};
for (let index = 0; index < argv.length; index += 1) {
const arg = argv[index];
if (arg === "--skip-artifact-download") {
result.verifyArtifacts = false;
continue;
}
const value = argv[index + 1];
if (["--release-file", "--versions-file", "--catalog-file"].includes(arg)) {
if (!value || value.startsWith("--")) {
throw new Error(`missing value for ${arg}`);
}
if (arg === "--release-file") result.releaseFiles.push(value);
if (arg === "--versions-file") result.versionsFiles.push(value);
if (arg === "--catalog-file") result.catalogFile = value;
index += 1;
continue;
}
throw new Error(`unexpected argument: ${arg}`);
}
return result;
}
export async function main() {
const result = await verifyTuttiAppReleaseArtifacts(
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;
});
}
@@ -0,0 +1,42 @@
{
"name": "@tutti-os/app-release-tools",
"version": "0.1.1",
"private": false,
"type": "module",
"bin": {
"build-tutti-app-release": "./bin/build-tutti-app-release.mjs",
"build-tutti-app-catalog": "./bin/build-tutti-app-catalog.mjs",
"build-tutti-app-versions": "./bin/build-tutti-app-versions.mjs",
"merge-tutti-app-latest": "./bin/merge-tutti-app-latest.mjs",
"publish-tutti-app-catalog": "./bin/publish-tutti-app-catalog.mjs",
"publish-tutti-app-metadata": "./bin/publish-tutti-app-metadata.mjs",
"verify-tutti-app-release-artifacts": "./bin/verify-tutti-app-release-artifacts.mjs"
},
"exports": {
"./build-tutti-app-release": "./bin/build-tutti-app-release.mjs",
"./build-tutti-app-catalog": "./bin/build-tutti-app-catalog.mjs",
"./build-tutti-app-versions": "./bin/build-tutti-app-versions.mjs",
"./merge-tutti-app-latest": "./bin/merge-tutti-app-latest.mjs",
"./publish-tutti-app-catalog": "./bin/publish-tutti-app-catalog.mjs",
"./publish-tutti-app-metadata": "./bin/publish-tutti-app-metadata.mjs",
"./verify-tutti-app-release-artifacts": "./bin/verify-tutti-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"
},
"scripts": {
"build": "node -e \"\""
},
"publishConfig": {
"access": "public"
},
"dependencies": {
"semver": "7.8.0"
}
}