website-xp-phone 2.2.11 → 2.3.0

package/scripts/refresh-content.mjs

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
-import { run as refreshSoundcloud } from "./refresh-soundcloud.mjs";
+/**
+ * Validates and normalizes the authored JSON content under src/content.
+ *
+ * Deliberately does NOT regenerate live-data snapshots: soundcloud.json is
+ * rewritten by scripts/refresh-soundcloud.mjs (network-dependent), invoked
+ * by the `refresh:soundcloud` script. Keeping that out of here means every
+ * entry point that runs this script — including a deploy-side build — can
+ * only validate content, never re-generate it. Deploy builds must ship the
+ * committed snapshot exactly as `build:local` produced it.
+ */
 import { readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,52 +22,64 @@ const projectRoot = resolve(__dirname, "..");
  * that `verify:policy` (which may run before `checksums`) does not act on a
  * report produced by a previous build.  The checksums step rewrites it.
  */
-const driftReportPath = resolve(projectRoot, "public", "documents", "drift-report.json");
+const driftReportPath = resolve(
+  projectRoot,
+  "public",
+  "documents",
+  "drift-report.json",
+);
 
 const contentRoot = resolve(projectRoot, "src/content");
 
 /** Every structural JSON file under src/content (recursively). */
 async function listContentJson(dir = contentRoot) {
-    const entries = await readdir(dir, { withFileTypes: true });
-    const nested = await Promise.all(
-        entries.map((entry) =>
-            entry.isDirectory()
-                ? listContentJson(resolve(dir, entry.name))
-                : entry.name.endsWith(".json")
-                  ? [resolve(dir, entry.name)]
-                  : [],
-        ),
-    );
-    return nested.flat();
+  const entries = await readdir(dir, { withFileTypes: true });
+  const nested = await Promise.all(
+    entries.map((entry) =>
+      entry.isDirectory()
+        ? listContentJson(resolve(dir, entry.name))
+        : entry.name.endsWith(".json")
+          ? [resolve(dir, entry.name)]
+          : [],
+    ),
+  );
+  return nested.flat();
 }
 
 async function validateLocalContent() {
-    for (const inputPath of await listContentJson()) {
-        const content = await readFile(inputPath, "utf8");
-        JSON.parse(content);
+  for (const inputPath of await listContentJson()) {
+    const content = await readFile(inputPath, "utf8");
+    JSON.parse(content);
 
-        // Normalize trailing newline so build outputs remain stable.
-        await writeFile(inputPath, `${content.trim()}\n`, "utf8");
-        process.stdout.write(`Validated local content: ${inputPath}\n`);
-    }
+    // Normalize trailing newline so build outputs remain stable.
+    await writeFile(inputPath, `${content.trim()}\n`, "utf8");
+    process.stdout.write(`Validated local content: ${inputPath}\n`);
+  }
 }
 
 export async function run() {
-    await unlink(driftReportPath).catch((error) => {
-        if (!(error && typeof error === "object" && "code" in error && error.code === "ENOENT")) {
-            throw error;
-        }
-    });
-    await validateLocalContent();
-    await refreshSoundcloud();
+  await unlink(driftReportPath).catch((error) => {
+    if (!(
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "ENOENT"
+    )) {
+      throw error;
+    }
+  });
+  await validateLocalContent();
 }
 
 const isDirectExecution =
-    process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === resolve(process.argv[1]);
 
 if (isDirectExecution) {
-    run().catch((error) => {
-        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-        process.exit(1);
-    });
+  run().catch((error) => {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exit(1);
+  });
 }

package/scripts/refresh-soundcloud.mjs

@@ -43,7 +43,7 @@ const SOUND_CLOUD_OWNERS = ["akinevz", "akinevz2"];
 
 /** User-Agent sent for every outbound HTTP request. */
 const USER_AGENT =
-    "Mozilla/5.0 (X11; Linux x86_64; rv:139.0) Gecko/20100101 Firefox/139.0";
+  "Mozilla/5.0 (X11; Linux x86_64; rv:139.0) Gecko/20100101 Firefox/139.0";
 
 /** Fetch timeout (ms) for every HTTP request. */
 const FETCH_TIMEOUT_MS = 15_000;
@@ -63,17 +63,17 @@ const getProfileUrl = (owner) => `https://soundcloud.com/${owner}`;
  * (callers decide how to interpret it); throws only on network failure.
  */
 const fetchWithTimeout = async (url, options = {}) => {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-    try {
-        return await fetch(url, {
-            ...options,
-            headers: { "User-Agent": USER_AGENT, ...options.headers },
-            signal: controller.signal,
-        });
-    } finally {
-        clearTimeout(timer);
-    }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    return await fetch(url, {
+      ...options,
+      headers: { "User-Agent": USER_AGENT, ...options.headers },
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
 };
 
 /**
@@ -82,21 +82,23 @@ const fetchWithTimeout = async (url, options = {}) => {
  * JSON.  Throws with the HTTP status on definitive failure.
  */
 const fetchApiJson = async (url, attempt = 1) => {
-    try {
-        const response = await fetchWithTimeout(url, {
-            headers: { Accept: "application/json" },
-        });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status} for ${new URL(url).pathname}`);
-        }
-        return await response.json();
-    } catch (error) {
-        if (attempt < API_RETRIES) {
-            await new Promise((resolveSleep) => setTimeout(resolveSleep, 1_000 * attempt));
-            return fetchApiJson(url, attempt + 1);
-        }
-        throw error;
+  try {
+    const response = await fetchWithTimeout(url, {
+      headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} for ${new URL(url).pathname}`);
+    }
+    return await response.json();
+  } catch (error) {
+    if (attempt < API_RETRIES) {
+      await new Promise((resolveSleep) =>
+        setTimeout(resolveSleep, 1_000 * attempt),
+      );
+      return fetchApiJson(url, attempt + 1);
     }
+    throw error;
+  }
 };
 
 /**
@@ -105,46 +107,53 @@ const fetchApiJson = async (url, attempt = 1) => {
  * they must never be hard-coded.  Throws if no bundle yields one.
  */
 const resolveClientId = async () => {
-    const profileResponse = await fetchWithTimeout(getProfileUrl(SOUND_CLOUD_OWNERS[0]));
-    if (!profileResponse.ok) {
-        throw new Error(`Could not fetch profile HTML: HTTP ${profileResponse.status}`);
-    }
-    const html = await profileResponse.text();
+  const profileResponse = await fetchWithTimeout(
+    getProfileUrl(SOUND_CLOUD_OWNERS[0]),
+  );
+  if (!profileResponse.ok) {
+    throw new Error(
+      `Could not fetch profile HTML: HTTP ${profileResponse.status}`,
+    );
+  }
+  const html = await profileResponse.text();
 
-    const assetUrls = [
-        ...new Set(
-            [...html.matchAll(/https:\/\/a-v2\.sndcdn\.com\/assets\/[a-zA-Z0-9._-]+\.js/g)].map(
-                (match) => match[0],
-            ),
+  const assetUrls = [
+    ...new Set(
+      [
+        ...html.matchAll(
+          /https:\/\/a-v2\.sndcdn\.com\/assets\/[a-zA-Z0-9._-]+\.js/g,
         ),
-    ];
-    if (assetUrls.length === 0) {
-        throw new Error("No SoundCloud asset bundles found in profile HTML");
-    }
+      ].map((match) => match[0]),
+    ),
+  ];
+  if (assetUrls.length === 0) {
+    throw new Error("No SoundCloud asset bundles found in profile HTML");
+  }
 
-    for (const assetUrl of assetUrls) {
-        const assetResponse = await fetchWithTimeout(assetUrl);
-        if (!assetResponse.ok) continue;
-        const js = await assetResponse.text();
-        const match = js.match(/client_id:"([a-zA-Z0-9]{20,40})"/);
-        if (match) return match[1];
-    }
+  for (const assetUrl of assetUrls) {
+    const assetResponse = await fetchWithTimeout(assetUrl);
+    if (!assetResponse.ok) continue;
+    const js = await assetResponse.text();
+    const match = js.match(/client_id:"([a-zA-Z0-9]{20,40})"/);
+    if (match) return match[1];
+  }
 
-    throw new Error("No client_id found in any SoundCloud asset bundle");
+  throw new Error("No client_id found in any SoundCloud asset bundle");
 };
 
 /**
- * Resolve an owner handle to its numeric SoundCloud user id.
+ * Resolve an owner handle to its public api-v2 user object (id plus
+ * profile metadata such as the public track_count).
  */
-const resolveUserId = async (owner, clientId) => {
-    const resolveUrl = new URL("https://api-v2.soundcloud.com/resolve");
-    resolveUrl.searchParams.set("url", getProfileUrl(owner));
-    resolveUrl.searchParams.set("client_id", clientId);
-    const user = await fetchApiJson(resolveUrl.toString());
-    if (typeof user?.id !== "number") {
-        throw new Error(`Could not resolve user id for ${owner}`);
-    }
-    return user.id;
+const resolveUser = async (owner, clientId) => {
+  const resolveUrl = new URL("https://api-v2.soundcloud.com/resolve");
+  resolveUrl.searchParams.set("url", getProfileUrl(owner));
+  resolveUrl.searchParams.set("client_id", clientId);
+  const user = await fetchApiJson(resolveUrl.toString());
+  if (typeof user?.id !== "number") {
+    throw new Error(`Could not resolve user id for ${owner}`);
+  }
+  return user;
 };
 
 /**
@@ -153,26 +162,27 @@ const resolveUserId = async (owner, clientId) => {
  * re-appended on every page or page 2+ returns HTTP 401.
  */
 const fetchAllTracks = async (owner, userId, clientId) => {
-    const tracks = [];
-    let href = `https://api-v2.soundcloud.com/users/${userId}/tracks?client_id=${clientId}&limit=200&representation=full`;
+  const tracks = [];
+  let href = `https://api-v2.soundcloud.com/users/${userId}/tracks?client_id=${clientId}&limit=200&representation=full`;
 
-    while (href) {
-        const page = await fetchApiJson(href);
-        const collection = Array.isArray(page?.collection) ? page.collection : [];
-        for (const track of collection) {
-            if (typeof track?.permalink_url !== "string") continue;
-            tracks.push(track);
-        }
-        const nextHref = typeof page?.next_href === "string" ? page.next_href : null;
-        href = nextHref
-            ? `${nextHref}${nextHref.includes("?") ? "&" : "?"}client_id=${clientId}`
-            : null;
+  while (href) {
+    const page = await fetchApiJson(href);
+    const collection = Array.isArray(page?.collection) ? page.collection : [];
+    for (const track of collection) {
+      if (typeof track?.permalink_url !== "string") continue;
+      tracks.push(track);
     }
+    const nextHref =
+      typeof page?.next_href === "string" ? page.next_href : null;
+    href = nextHref
+      ? `${nextHref}${nextHref.includes("?") ? "&" : "?"}client_id=${clientId}`
+      : null;
+  }
 
-    if (tracks.length === 0) {
-        throw new Error(`Discography for ${owner} came back empty`);
-    }
-    return tracks;
+  if (tracks.length === 0) {
+    throw new Error(`Discography for ${owner} came back empty`);
+  }
+  return tracks;
 };
 
 /**
@@ -180,87 +190,116 @@ const fetchAllTracks = async (owner, userId, clientId) => {
  * URL slug if the title is missing.
  */
 const toSnapshotTrack = (owner, track) => {
-    const url = track.permalink_url;
-    const path = `/${url.replace(/^https?:\/\/(www\.)?soundcloud\.com\//, "")}`;
-    return {
-        owner,
-        path,
-        title:
-            typeof track.title === "string" && track.title.length > 0
-                ? track.title
-                : path.split("/").pop(),
-        url,
-    };
+  const url = track.permalink_url;
+  const path = `/${url.replace(/^https?:\/\/(www\.)?soundcloud\.com\//, "")}`;
+  return {
+    owner,
+    path,
+    title:
+      typeof track.title === "string" && track.title.length > 0
+        ? track.title
+        : path.split("/").pop(),
+    url,
+  };
 };
 
 /**
  * Fetch the complete discography for one owner.  Returns the snapshot-shaped
  * track list in API order (newest first).
  */
+/**
+ * Fetch the complete discography for one owner.  Returns the snapshot-shaped
+ * track list in API order (newest first).
+ *
+ * Integrity: the fetched list must match the profile's PUBLIC track_count —
+ * the number any anonymous visitor (and this unauthenticated snapshot) can
+ * see.  A mismatch means the list came back truncated or the API lagged a
+ * fresh upload; retry once, then fail loudly rather than write a silently
+ * incomplete discography.  (Tracks the owner sees but the public does not —
+ * still processing or private — never inflate the public count, so they do
+ * not trip this check.)
+ */
 const fetchOwnerDiscography = async (owner, clientId) => {
-    const userId = await resolveUserId(owner, clientId);
-    const apiTracks = await fetchAllTracks(owner, userId, clientId);
-    return apiTracks.map((track) => toSnapshotTrack(owner, track));
+  const user = await resolveUser(owner, clientId);
+  let apiTracks = await fetchAllTracks(owner, user.id, clientId);
+  const publicCount =
+    typeof user.track_count === "number" ? user.track_count : null;
+  if (publicCount !== null && apiTracks.length !== publicCount) {
+    apiTracks = await fetchAllTracks(owner, user.id, clientId);
+    if (apiTracks.length !== publicCount) {
+      throw new Error(
+        `Discography for ${owner} returned ${apiTracks.length} track(s) ` +
+          `but the public profile counts ${publicCount} — refusing to ` +
+          `write a truncated snapshot`,
+      );
+    }
+  }
+  return apiTracks.map((track) => toSnapshotTrack(owner, track));
 };
 
 export const run = async () => {
-    const clientId = await resolveClientId();
-    process.stdout.write(`Resolved SoundCloud client_id: ${clientId}\n`);
+  const clientId = await resolveClientId();
+  process.stdout.write(`Resolved SoundCloud client_id: ${clientId}\n`);
 
-    const discographies = new Map();
-    for (const owner of SOUND_CLOUD_OWNERS) {
-        discographies.set(owner, await fetchOwnerDiscography(owner, clientId));
-    }
+  const discographies = new Map();
+  for (const owner of SOUND_CLOUD_OWNERS) {
+    discographies.set(owner, await fetchOwnerDiscography(owner, clientId));
+  }
 
-    // Flat track list in per-owner API order (newest first).  The music page
-    // filters this array by `owner`, so per-owner relative order is what the
-    // UI displays.
-    const tracks = SOUND_CLOUD_OWNERS.flatMap((owner) => discographies.get(owner) ?? []);
-    const trackCount = tracks.length;
+  // Flat track list in per-owner API order (newest first).  The music page
+  // filters this array by `owner`, so per-owner relative order is what the
+  // UI displays.
+  const tracks = SOUND_CLOUD_OWNERS.flatMap(
+    (owner) => discographies.get(owner) ?? [],
+  );
+  const trackCount = tracks.length;
 
-    // Per-owner sections.  The component groups the discography by `owner`,
-    // so emitting a `profiles` array ensures every owner gets its own
-    // section — not just the first one.
-    const profiles = SOUND_CLOUD_OWNERS.map((owner) => {
-        const ownerTracks = discographies.get(owner) ?? [];
-        return {
-            owner,
-            source: getProfileUrl(owner),
-            profileImageUrl: null,
-            trackCount: ownerTracks.length,
-            tracks: ownerTracks,
-        };
-    });
-
-    const result = {
-        source: getProfileUrl(SOUND_CLOUD_OWNERS[0]),
-        generatedAt: new Date().toISOString(),
-        asOfUploadingTrackCount: trackCount,
-        trackCount,
-        tracks,
-        profiles,
+  // Per-owner sections.  The component groups the discography by `owner`,
+  // so emitting a `profiles` array ensures every owner gets its own
+  // section — not just the first one.
+  const profiles = SOUND_CLOUD_OWNERS.map((owner) => {
+    const ownerTracks = discographies.get(owner) ?? [];
+    return {
+      owner,
+      source: getProfileUrl(owner),
+      profileImageUrl: null,
+      trackCount: ownerTracks.length,
+      tracks: ownerTracks,
     };
+  });
 
-    await writeFile(outputFile, `${JSON.stringify(result, null, 2)}\n`, "utf8");
+  const result = {
+    source: getProfileUrl(SOUND_CLOUD_OWNERS[0]),
+    generatedAt: new Date().toISOString(),
+    asOfUploadingTrackCount: trackCount,
+    trackCount,
+    tracks,
+    profiles,
+  };
 
-    process.stdout.write(
-        `Refreshed ${result.tracks.length} SoundCloud track(s) into ${outputFile}\n` +
-        profiles
-            .map((profile) => `  @${profile.owner}: ${profile.trackCount} track(s)\n`)
-            .join(""),
-    );
+  await writeFile(outputFile, `${JSON.stringify(result, null, 2)}\n`, "utf8");
 
-    return result;
+  process.stdout.write(
+    `Refreshed ${result.tracks.length} SoundCloud track(s) into ${outputFile}\n` +
+      profiles
+        .map(
+          (profile) => `  @${profile.owner}: ${profile.trackCount} track(s)\n`,
+        )
+        .join(""),
+  );
+
+  return result;
 };
 
 const isDirectExecution =
-    process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === resolve(process.argv[1]);
 
 if (isDirectExecution) {
-    run().catch((error) => {
-        process.stderr.write(
-            `${error instanceof Error ? error.message : String(error)}\n`,
-        );
-        process.exit(1);
-    });
+  run().catch((error) => {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exit(1);
+  });
 }

package/scripts/write-dist-checksums.mjs

@@ -39,6 +39,7 @@ const distRoot = resolve(projectRoot, "dist");
 const publicRoot = resolve(projectRoot, "public");
 const distChecksumsPath = resolve(distRoot, "checksums.txt");
 const publicChecksumsPath = resolve(publicRoot, "checksums.txt");
+const generatedManifestPath = resolve(distRoot, ".generated.json");
 
 /**
  * Sidecar written next to `checksums.txt` capturing any STABLE-invariant
@@ -191,9 +192,48 @@ async function readRemoteChecksums() {
   }
 }
 
+/**
+ * Read the generated-artifact manifest that routeSkeletonsPlugin emits
+ * (`dist/.generated.json`): every webapp-generated path it lists is
+ * auto-marked mutable, so new routes and project pages never need a
+ * hand-maintained mutable entry.
+ *
+ * Fail-loud policy: an existing but corrupt manifest throws (a build
+ * tooling regression must not silently downgrade the gate); a missing
+ * manifest only notes it — pages then fall back to the denylist in
+ * mutable-assets.mjs and the live-reconcile in the drift gate.
+ */
+async function readGeneratedPaths() {
+  let raw;
+  try {
+    raw = await readFile(generatedManifestPath, "utf8");
+  } catch {
+    process.stdout.write(
+      `Note: no generated-artifact manifest at dist/.generated.json — ` +
+        `generated pages are not auto-marked mutable (run vite build first)\n`,
+    );
+    return new Set();
+  }
+
+  const parsed = JSON.parse(raw);
+  const list =
+    parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed.generated
+      : null;
+  if (!Array.isArray(list) || list.some((p) => typeof p !== "string")) {
+    throw new Error(
+      `corrupt generated-artifact manifest: ` +
+        `${relative(projectRoot, generatedManifestPath)} must be ` +
+        `{ "generated": string[] }`,
+    );
+  }
+  return new Set(list);
+}
+
 async function run() {
   const files = await walk(distRoot);
   const existing = await readRemoteChecksums();
+  const generatedPaths = await readGeneratedPaths();
   const rows = [];
   let index = 0;
   const driftViolations = [];
@@ -202,8 +242,9 @@ async function run() {
   const liveCounterparts = new Map();
 
   for (const filePath of files.sort()) {
-    // Skip the manifest file itself so it doesn't appear in its own diff.
-    if (filePath === distChecksumsPath) {
+    // Skip the manifest file itself and the generated-artifact manifest so
+    // neither appears in its own diff.
+    if (filePath === distChecksumsPath || filePath === generatedManifestPath) {
       continue;
     }
 
@@ -216,11 +257,13 @@ async function run() {
       : previous === digest
         ? "STABLE"
         : "CHANGED";
-    const mutable = isMutablePath(relPath);
+    const generated = generatedPaths.has(relPath);
+    const mutable = generated || isMutablePath(relPath);
+    const tag = generated ? " (generated)" : mutable ? " (mutable)" : "";
     index += 1;
 
     process.stdout.write(
-      `${String(index).padStart(3, "0")}. [${status}] ${relPath}${mutable ? " (mutable)" : ""}\n` +
+      `${String(index).padStart(3, "0")}. [${status}] ${relPath}${tag}\n` +
         `     prev: ${previous ?? "(none)"}\n` +
         `     next: ${digest}\n`,
     );
@@ -266,6 +309,7 @@ async function run() {
       baselineUrl: REMOTE_CHECKSUMS_URL,
       generatedAt: new Date().toISOString(),
       mutablePaths: [...MUTABLE_PATH_SET],
+      generatedPaths: [...generatedPaths].sort(),
       violationCount: driftViolations.length,
       violations: driftViolations,
       rehashOnlyCount: rehashOnly.length,