@tutti-os/app-release-tools 0.0.78 → 0.0.80

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

@@ -0,0 +1,236 @@
+#!/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,
+  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 = requireSemver(
+      options.minTuttiVersion,
+      "minTuttiVersion"
+    );
+    const status = normalizeStatus(options.status ?? "active");
+    for (const releaseFile of releaseFiles) {
+      const release = JSON.parse(await readFile(releaseFile, "utf8"));
+      validateRelease(release);
+      document = addVersionRecord(document, {
+        minTuttiVersion,
+        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`);
+    }
+    record.minTuttiVersion = requireSemver(
+      record.minTuttiVersion,
+      `${label}.minTuttiVersion`
+    );
+    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;
+  });
+}

package/bin/merge-tutti-app-latest.mjs

@@ -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;
+  });
+}

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

@@ -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;
+  });
+}