源码快照 @ 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
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:
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;
|
||||
}
|
||||
+302
@@ -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"
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user