Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

6.9 KB
Raw Blame
#!/usr/bin/env node
import fs from "node:fs";
import path from "node:path";
import process from "node:process";
import { fileURLToPath } from "node:url";

const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const dataPath = path.join(root, "docs/comparison-data.json");
const readmePath = path.join(root, "README.md");
const detailPath = path.join(root, "docs/COMPARISON.md");
const check = process.argv.includes("--check");
const allowedRatings = new Set(["strong", "partial", "none"]);
const requiredLabels = { strong: "Strong", partial: "Partial", none: "Not offered" };
const officialHosts = new Set([
  "github.com",
  "cockpit-project.org",
  "coolify.io",
  "next.coolify.io",
  "docs.portainer.io",
  "learn.netdata.cloud",
  "tailscale.com",
  "runtipi.io"
]);

const data = JSON.parse(fs.readFileSync(dataPath, "utf8"));
const fail = (message) => { console.error(`comparison: ${message}`); process.exit(1); };
const escape = (value) => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");

if (data.schemaVersion !== 1) fail("unsupported schemaVersion");
if (!Array.isArray(data.criteria) || !data.criteria.length) fail("criteria are required");
if (!Array.isArray(data.products) || !data.products.length) fail("products are required");
for (const [rating, label] of Object.entries(requiredLabels)) {
  if (data.legend?.[rating] !== label) fail(`legend.${rating} must be the SEO-readable text ${JSON.stringify(label)}`);
}
const reviewed = new Date(`${data.reviewedAt}T00:00:00Z`);
if (!Number.isFinite(reviewed.getTime())) fail("reviewedAt must be YYYY-MM-DD");
const ageDays = Math.floor((Date.now() - reviewed.getTime()) / 86_400_000);
if (ageDays < -1) fail("reviewedAt is in the future");
if (ageDays > data.expiresAfterDays) fail(`comparison review is ${ageDays} days old; refresh official sources and reviewedAt`);

const criteria = data.criteria.map((criterion) => criterion.id);
const productIds = new Set();
for (const product of data.products) {
  if (!product.id || productIds.has(product.id)) fail(`duplicate/missing product id: ${product.id}`);
  productIds.add(product.id);
  for (const criterion of criteria) {
    const rating = product.ratings?.[criterion];
    if (!rating || !allowedRatings.has(rating.value)) fail(`${product.id}.${criterion} has no valid rating`);
    if (product.id === "mso") {
      for (const evidence of rating.evidence ?? []) {
        if (path.isAbsolute(evidence) || evidence.includes("..") || !fs.existsSync(path.join(root, evidence))) {
          fail(`missing/unsafe MSO evidence: ${evidence}`);
        }
      }
      if (!(rating.evidence ?? []).length) fail(`MSO rating ${criterion} requires repository evidence`);
    }
  }
  if (!Array.isArray(product.sources) || !product.sources.length) fail(`${product.id} requires official sources`);
  for (const source of product.sources) {
    let url;
    try { url = new URL(source.url); } catch { fail(`${product.id} has invalid source URL`); }
    if (url.protocol !== "https:" || !officialHosts.has(url.hostname)) fail(`${product.id} source is not on an approved official host: ${source.url}`);
  }
}

const ratingLabel = (value) => data.legend[value];
const tableHeader = `| Product | Best fit | ${data.criteria.map((criterion) => escape(criterion.label)).join(" | ")} |`;
const tableRule = `|---|---|${data.criteria.map(() => ":---:").join("|")}|`;
const tableRows = data.products.map((product) =>
  `| **${escape(product.name)}** | ${escape(product.bestFor)} | ${data.criteria.map((criterion) => ratingLabel(product.ratings[criterion.id].value)).join(" | ")} |`
);
const compact = `[Product comparison, evidence and limitations](docs/COMPARISON.md) · reviewed ${data.reviewedAt}.`;

const start = "<!-- comparison:start -->";
const end = "<!-- comparison:end -->";
const readme = fs.readFileSync(readmePath, "utf8");
const startIndex = readme.indexOf(start);
const endIndex = readme.indexOf(end);
if (startIndex < 0 || endIndex < startIndex) fail("README comparison markers are missing");
const nextReadme = `${readme.slice(0, startIndex + start.length)}\n${compact}\n${readme.slice(endIndex)}`;

const details = [
  "<!-- Generated by scripts/gen-comparison.mjs from docs/comparison-data.json. Do not edit by hand. -->",
  "# Product comparison",
  "",
  `Last reviewed: **${data.reviewedAt}** · freshness gate: **${data.expiresAfterDays} days**`,
  "",
  data.positioning,
  "",
  "## Method",
  "",
  "- Ratings describe the documented product surface, not speed, popularity, or a universal winner.",
  "- `Strong` means a first-class product strength, `Partial` means available with deliberate scope limitations, and `Not offered` means it is not a core product surface.",
  "- MSO cells must point to repository evidence that exists at build time.",
  "- Competitor claims use official project documentation only and must be manually re-reviewed before the freshness window expires.",
  "- Edition-dependent or adjacent capabilities are marked partial unless they are consistently core to the product.",
  "",
  "## Criteria",
  "",
  ...data.criteria.flatMap((criterion) => [`### ${criterion.label}`, "", criterion.definition, ""]),
  "## Matrix",
  "",
  tableHeader,
  tableRule,
  ...tableRows,
  "",
  "## Notes and evidence",
  "",
  ...data.products.flatMap((product) => [
    `### ${product.name}`,
    "",
    `**Best fit:** ${product.bestFor}`,
    "",
    ...data.criteria.flatMap((criterion) => {
      const rating = product.ratings[criterion.id];
      const evidence = (rating.evidence ?? []).length
        ? ` Evidence: ${(rating.evidence ?? []).map((entry) => `\`${entry}\``).join(", ")}.`
        : "";
      return [`- **${criterion.label} (${ratingLabel(rating.value)}):** ${rating.note}${evidence}`];
    }),
    "",
    "Official sources:",
    ...product.sources.map((source) => `- [${source.label}](${source.url})`),
    "",
  ]),
  "## Interpretation",
  "",
  "MSO can lead its chosen category by integrating daily work that otherwise requires several tools: files, PTY, editors, service/package visibility, managed apps, device-scoped roles, AI, MCP, and CLI parity. It should not dilute that advantage by pretending to be a deeper Linux administrator than Cockpit, a broader PaaS than Coolify, a stronger container control plane than Portainer, a richer observability platform than Netdata, or a stronger identity network than Tailscale.",
  "",
].join("\n");

function writeOrCheck(file, next) {
  let current = "";
  try { current = fs.readFileSync(file, "utf8"); }
  catch (error) { if (error?.code !== "ENOENT") throw error; }
  if (check) {
    if (current !== next) fail(`${path.relative(root, file)} is stale; run node scripts/gen-comparison.mjs`);
  } else {
    fs.writeFileSync(file, next);
    console.log(`wrote ${path.relative(root, file)}`);
  }
}

writeOrCheck(readmePath, nextReadme);
writeOrCheck(detailPath, details);
if (check) console.log(`comparison: current — ${data.products.length} products, ${data.criteria.length} criteria, reviewed ${data.reviewedAt}`);