@cloudglue/tinycloud 0.3.0

package/LICENSE.md

@@ -0,0 +1 @@
+© Aviary Inc. (d/b/a Cloudglue). All rights reserved. Use is subject to Aviary Inc. Terms of Service (https://cloudglue.dev/terms).

package/README.md

@@ -0,0 +1,104 @@
+# Tinycloud
+
+Agent CLI for deep video work. Point it at videos and ask for analysis,
+dashboards, subtitles, clips, search, or repurposed content — or drive its
+verbs directly from your own agent. Powered by [Cloudglue](https://cloudglue.dev).
+Learn more at [tinycloud.sh](https://tinycloud.sh).
+
+## Install
+
+```bash
+npm install -g @cloudglue/tinycloud     # then: tinycloud
+npx @cloudglue/tinycloud                # or run directly
+```
+
+The npm package is a small launcher: on first run it downloads the matching
+platform distribution from Cloudglue's CDN (cached under
+`~/.tinycloud/versions/<version>/`), verifies its checksum, and execs the real
+binary. The package version pins the binary version, so
+`npx @cloudglue/tinycloud@0.3.0` always runs tinycloud 0.3.0. It also adds two
+wrapper commands:
+
+```bash
+tinycloud install --version 0.3.0   # pre-download a version
+tinycloud install --latest          # install latest stable and pin to it
+tinycloud update                    # move to latest stable, prune old versions
+```
+
+Alternatively, the shell installer (installs to `~/.tinycloud/bin` and adds
+it to your PATH):
+
+```bash
+curl -fsSL https://app.cloudglue.dev/tinycloud.sh | bash
+```
+
+Platforms: macOS (arm64, x64) and Linux (x64, arm64). Windows is not
+supported — use WSL2.
+
+### Setup
+
+Cloud features need a Cloudglue API key:
+
+```bash
+tinycloud setup cloudglue --api-key <key>   # or: export CLOUDGLUE_API_KEY=...
+tinycloud setup --check --json              # verify
+```
+
+## Use tinycloud from your agent
+
+This repo also distributes agent skills that teach coding agents (Claude
+Code, Codex, and anything else following the
+[Agent Skills](https://agentskills.io) standard) to drive the tinycloud CLI.
+
+**One command** (detects your agent and installs the bundled skills):
+
+```bash
+npx @cloudglue/tinycloud skills install          # project-level (.claude/skills, .agents/skills)
+npx @cloudglue/tinycloud skills install --global # ~/.claude/skills (all your projects)
+npx @cloudglue/tinycloud skills install --skill tinycloud,blog-post   # just some
+```
+
+**Claude Code** (as a plugin):
+
+```text
+/plugin marketplace add cloudglue/tinycloud
+/plugin install tinycloud@cloudglue
+```
+
+Also works with the generic installer (`npx skills add cloudglue/tinycloud`)
+or a plain copy (`cp -r skills/* ~/.claude/skills/`).
+
+| Skill | What it does |
+|---|---|
+| `tinycloud-init` | First-time setup: install the CLI, configure the API key, verify with a free command |
+| `tinycloud` | The general skill: full CLI usage, JSON envelope contract, verbs, workflows, glossary, troubleshooting |
+| `sales-coaching` | Sales call → coaching dashboard (scores, speech metrics, objections) |
+| `blog-post` | Video → rich blog post with sections, thumbnails, takeaways |
+| `ad-analysis` | Video ad → shot timeline, hook, pacing, CTA breakdown |
+| `meeting-breakdown` | Meeting recording → speaker timeline, summaries, action items |
+| `youtube-publish` | Video → YouTube title, description, chapters, tags, subtitles |
+| `tinycloud-skill-creator` | Author your own tinycloud-powered skills (recipe + render script) |
+
+New to tinycloud? Invoke `tinycloud-init` in your agent for guided setup.
+Each skill checks compatibility via the general skill's
+`scripts/preflight.sh`, which gates on the installed binary's version and
+feature ids (`skills/tinycloud/tinycloud-skill.json` declares the
+requirements).
+
+### Team setup
+
+To give every agent session in a repo the same skills, commit them:
+
+```bash
+cd your-project
+npx @cloudglue/tinycloud skills install     # writes .claude/skills/ (and .agents/skills/ if present)
+git add .claude .agents 2>/dev/null; git commit -m "Add tinycloud agent skills"
+```
+
+Optionally add a line to your project's `CLAUDE.md` so agents reach for them:
+`Video work (analysis, captions, clips, workflows) goes through the tinycloud
+CLI — see the tinycloud skill; run tinycloud-init if the CLI isn't set up.`
+
+## License
+
+© Aviary Inc. (d/b/a Cloudglue). All rights reserved. Use is subject to [Aviary Inc. Terms of Service](https://cloudglue.dev/terms).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+# Third-Party Notices
+
+This file lists third-party software included in or used by Tinycloud, along with their respective licenses.
+
+## Bun
+- Version: 1.x (bundled runtime)
+- License: MIT
+- https://bun.sh
+- https://github.com/oven-sh/bun
+
+## FFmpeg
+- Version: 5.3.0 (bundled binary)
+- License: GPL-3.0-or-later
+- Source: https://ffmpeg.org/download.html
+- Binary obtained via: https://github.com/eugeneware/ffmpeg-static
+
+## ffprobe (bundled with FFmpeg)
+- Version: 3.1.0 (bundled binary)
+- License: GPL-3.0-or-later
+- Source: https://ffmpeg.org/download.html
+- Binary obtained via: https://github.com/joshwnj/ffprobe-static
+
+## chalk
+- Version: 5.6.2
+- License: MIT
+- https://github.com/chalk/chalk
+
+## @mariozechner/pi-agent-core
+- Version: 0.55.3
+- License: MIT
+- https://github.com/badlogic/pi-mono
+
+## @mariozechner/pi-ai
+- Version: 0.55.3
+- License: MIT
+- https://github.com/badlogic/pi-mono
+
+## @mariozechner/pi-tui
+- Version: 0.55.3
+- License: MIT
+- https://github.com/badlogic/pi-mono

package/bin/tinycloud.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+"use strict";
+
+const path = require("node:path");
+const { resolveTarget } = require("../lib/platform");
+const {
+  ensureInstalled,
+  pruneVersions,
+  readOverrideVersion,
+  writeOverrideVersion,
+  normalizeVersion,
+  isInstalled,
+} = require("../lib/installer");
+const { fetchManifest } = require("../lib/manifest");
+const { cmdSkills } = require("../lib/skills");
+const { run } = require("../lib/run");
+const pkg = require("../package.json");
+
+function pickVersion() {
+  return normalizeVersion(process.env.TINYCLOUD_VERSION || readOverrideVersion() || pkg.version);
+}
+
+/**
+ * pickVersion() for advisory uses (prune-protect lists): a malformed
+ * TINYCLOUD_VERSION should fail the run path loudly, but it must not crash
+ * an install/update that never needed it.
+ */
+function pickVersionSafe() {
+  try {
+    return pickVersion();
+  } catch {
+    return null;
+  }
+}
+
+async function cmdInstall(args, target) {
+  let version = null;
+  let latest = false;
+  let prune = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--version" && args[i + 1]) version = normalizeVersion(args[++i]);
+    else if (args[i] === "--latest") latest = true;
+    else if (args[i] === "--prune") prune = true;
+    else throw new Error(`Unknown install option: ${args[i]} (expected --version <v>, --latest, or --prune)`);
+  }
+  if (latest && version) throw new Error("install options --version and --latest cannot be used together");
+  if (prune && (latest || version)) {
+    // Combining an install spec with --prune is ambiguous (two Bugbot
+    // findings pulled opposite ways here): --prune is standalone cache
+    // maintenance. `tinycloud update` is install-latest-and-prune.
+    throw new Error(
+      "--prune is a standalone action: run the install first, then `tinycloud install --prune` (or use `tinycloud update`)"
+    );
+  }
+  if (prune) {
+    // Protect what the run path resolves to (env pin / wrapper-version /
+    // package default). A "latest" pin is resolved to its concrete version —
+    // the literal string would never match a versions/<semver>/ cache dir,
+    // leaving the tree latest actually runs unprotected.
+    let protect = [pickVersionSafe()].filter(Boolean);
+    if (protect.includes("latest")) {
+      const manifest = await fetchManifest().catch(() => null);
+      const stable = manifest && manifest.channels && manifest.channels.stable;
+      const resolved = stable ? normalizeVersion(stable) : null;
+      if (!resolved) {
+        // Don't guess: pruning by age could delete the tree the pin runs.
+        process.stderr.write(
+          "tinycloud: cannot resolve the 'latest' pin without the release manifest — skipping prune\n"
+        );
+        return;
+      }
+      protect = protect.map((p) => (p === "latest" ? resolved : p)).filter(Boolean);
+    }
+    const removed = pruneVersions(2, protect, target);
+    console.log(removed.length ? `Pruned: ${removed.join(", ")}` : "Nothing to prune.");
+    return;
+  }
+  // An explicit --version wins without consulting the env/override, so a
+  // malformed TINYCLOUD_VERSION can't block an explicit install.
+  if (!version && !latest) version = pickVersion();
+  let manifest;
+  if (latest) {
+    manifest = await fetchManifest();
+    if (!manifest) throw new Error("`install --latest` requires the release manifest, which is not available");
+    version = manifest.channels && manifest.channels.stable;
+    if (!version) throw new Error("The release manifest has no stable version");
+  }
+  const res = await ensureInstalled(version, target, { manifest });
+  if (latest) writeOverrideVersion(res.version);
+  console.log(`tinycloud ${res.version} installed at ${res.dir}`);
+}
+
+async function cmdUpdate(target) {
+  const manifest = await fetchManifest();
+  if (!manifest) throw new Error("`update` requires the release manifest, which is not available");
+  const version = normalizeVersion(manifest.channels && manifest.channels.stable);
+  if (!version) throw new Error("The release manifest has no stable version");
+  const alreadyCurrent = isInstalled(version, target);
+  const res = await ensureInstalled(version, target, { manifest });
+  writeOverrideVersion(res.version);
+  // Protect both the new stable and whatever the run path still resolves to
+  // (e.g. a TINYCLOUD_VERSION env pin). Advisory only — a malformed env
+  // value must not fail an update that already completed. A "latest" pin
+  // resolves to the stable we just installed.
+  const pinned = pickVersionSafe();
+  const removed = pruneVersions(2, [res.version, pinned === "latest" ? res.version : pinned].filter(Boolean), target);
+  console.log(
+    alreadyCurrent
+      ? `tinycloud ${res.version} is already current (${res.dir})`
+      : `tinycloud updated to ${res.version} (${res.dir})`
+  );
+  if (removed.length) console.log(`Pruned old versions: ${removed.join(", ")}`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  // Wrapper-owned subcommands. The binary has no install/update/skills
+  // verbs; these names are reserved with the binary owners (guarded by a
+  // regression test in the source repo). `skills` only copies bundled
+  // files, so it dispatches before the platform gate (works on Windows).
+  if (args[0] === "skills") return cmdSkills(args.slice(1));
+
+  const target = resolveTarget();
+  if (args[0] === "install") return cmdInstall(args.slice(1), target);
+  if (args[0] === "update") return cmdUpdate(target);
+
+  const { dir } = await ensureInstalled(pickVersion(), target);
+  run(path.join(dir, "tinycloud"), args, dir);
+}
+
+main().catch((err) => {
+  process.stderr.write(`tinycloud: ${err.message}\n`);
+  process.exit(typeof err.exitCode === "number" ? err.exitCode : 1);
+});

package/lib/download.js

@@ -0,0 +1,71 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const { execFileSync } = require("node:child_process");
+const { Readable } = require("node:stream");
+const { pipeline } = require("node:stream/promises");
+
+function fmtMB(bytes) {
+  return (bytes / 1048576).toFixed(1);
+}
+
+function sha256File(path) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(path));
+  return hash.digest("hex");
+}
+
+/**
+ * Download a URL to a file, computing sha256 in the same pass. Shows progress
+ * on stderr when it's a TTY. Node's fetch ignores proxy env vars, so when an
+ * HTTPS proxy is configured we shell out to curl instead.
+ * @returns {Promise<{sha256: string, etag: string|null}>}
+ */
+async function downloadWithHash(url, destPath) {
+  const proxy = process.env.HTTPS_PROXY || process.env.https_proxy;
+  if (proxy || process.env.TINYCLOUD_USE_CURL === "1") {
+    const headerFile = `${destPath}.headers`;
+    execFileSync("curl", ["-fsSL", "-D", headerFile, "-o", destPath, url], {
+      stdio: ["ignore", "ignore", "inherit"],
+    });
+    let etag = null;
+    try {
+      const m = fs.readFileSync(headerFile, "utf8").match(/^etag:\s*(.+)$/im);
+      etag = m ? m[1].trim() : null;
+      fs.unlinkSync(headerFile);
+    } catch {}
+    return { sha256: sha256File(destPath), etag };
+  }
+
+  const res = await fetch(url);
+  if (res.status === 403 || res.status === 404) {
+    throw new Error(`Download not found: ${url} (HTTP ${res.status}) — the requested version may not be published`);
+  }
+  if (!res.ok || !res.body) throw new Error(`Download failed: ${url} (HTTP ${res.status})`);
+
+  const etag = res.headers.get("etag");
+  const total = Number(res.headers.get("content-length")) || 0;
+  const hash = crypto.createHash("sha256");
+  const out = fs.createWriteStream(destPath);
+  const showProgress = process.stderr.isTTY;
+  let received = 0;
+  let lastRender = 0;
+
+  const source = Readable.fromWeb(res.body);
+  source.on("data", (chunk) => {
+    hash.update(chunk);
+    received += chunk.length;
+    const now = Date.now();
+    if (showProgress && now - lastRender > 250) {
+      lastRender = now;
+      const pct = total ? ` (${Math.floor((received / total) * 100)}%)` : "";
+      process.stderr.write(`\rtinycloud: downloading ${fmtMB(received)}/${total ? fmtMB(total) : "?"} MB${pct}`);
+    }
+  });
+  await pipeline(source, out);
+  if (showProgress) process.stderr.write("\n");
+  return { sha256: hash.digest("hex"), etag };
+}
+
+module.exports = { downloadWithHash, sha256File };

package/lib/installer.js

@@ -0,0 +1,300 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { execFileSync } = require("node:child_process");
+const { resolveDownload, httpHeadEtag } = require("./manifest");
+const { downloadWithHash } = require("./download");
+
+function rootDir() {
+  return process.env.TINYCLOUD_INSTALL_DIR || path.join(os.homedir(), ".tinycloud");
+}
+
+/**
+ * Accept v-prefixed versions everywhere a version is taken ("v0.3.0" ==
+ * "0.3.0"), and reject anything that isn't a plain version token — version
+ * strings become cache directory names, so path separators or ".." would
+ * escape ~/.tinycloud/versions.
+ */
+function normalizeVersion(version) {
+  if (typeof version !== "string") return version;
+  const v = version.replace(/^v/, "");
+  if (v !== "latest" && !/^[0-9A-Za-z][0-9A-Za-z.+_-]*$/.test(v)) {
+    throw new Error(`Invalid version "${version}" (expected a version like 0.3.0)`);
+  }
+  return v;
+}
+
+/**
+ * Is this version installed — and, when `target` is given, installed for
+ * this platform? A cache root synced across machines (network home, mounted
+ * volume) can hold another OS/arch's extract under the same version.
+ */
+function isInstalled(version, target) {
+  const okPath = path.join(versionDir(version), ".ok");
+  if (!fs.existsSync(okPath)) return false;
+  if (!hasExecutableBinary(versionDir(version))) return false;
+  if (!target) return true;
+  try {
+    const meta = JSON.parse(fs.readFileSync(okPath, "utf8"));
+    if (meta.target) return meta.target === target;
+    // Older .ok files lack the target; the recorded URL embeds it.
+    if (meta.url) return String(meta.url).includes(`tinycloud-${target}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function versionDir(version) {
+  return path.join(rootDir(), "versions", version);
+}
+
+function hasExecutableBinary(dir) {
+  try {
+    fs.accessSync(path.join(dir, "tinycloud"), fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function overrideFile() {
+  return path.join(rootDir(), "wrapper-version");
+}
+
+/** Newest healthy cached install for this platform, or null. */
+function findNewestHealthy(target) {
+  const dir = path.join(rootDir(), "versions");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const healthy = entries
+    .filter((v) => isInstalled(v, target))
+    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  if (!healthy.length) return null;
+  const version = healthy[healthy.length - 1];
+  return { dir: path.join(dir, version), version };
+}
+
+/** Scan installed versions for a .ok recorded from the same URL + ETag. */
+function findInstalledByUrlEtag(url, etag) {
+  const dir = path.join(rootDir(), "versions");
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  for (const v of entries) {
+    try {
+      const meta = JSON.parse(fs.readFileSync(path.join(dir, v, ".ok"), "utf8"));
+      if (meta.url === url && meta.etag && meta.etag === etag && hasExecutableBinary(path.join(dir, v))) {
+        return { dir: path.join(dir, v), version: v };
+      }
+    } catch {}
+  }
+  return null;
+}
+
+function readOverrideVersion() {
+  try {
+    const v = fs.readFileSync(overrideFile(), "utf8").trim();
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
+function writeOverrideVersion(version) {
+  fs.mkdirSync(rootDir(), { recursive: true });
+  fs.writeFileSync(overrideFile(), version + "\n");
+}
+
+/**
+ * Ensure the given version is installed under <root>/versions/<version>.
+ * Returns the install dir. Concurrency-safe via extract-then-atomic-rename:
+ * a half-extracted directory never carries the .ok marker, and a lost rename
+ * race just means another process won.
+ *
+ * @param {string} version exact semver, or "latest" (resolved via manifest
+ *   when available; the latest alias tarball otherwise)
+ * @returns {Promise<{dir: string, version: string}>}
+ */
+async function ensureInstalled(version, target, opts = {}) {
+  version = normalizeVersion(version);
+  if (version !== "latest") {
+    if (isInstalled(version, target)) return { dir: versionDir(version), version };
+  }
+
+  try {
+    return await resolveAndInstall(version, target, opts);
+  } catch (err) {
+    // "latest" means "the best you can give me": when resolution or the
+    // download is unreachable but a healthy install is cached, run that
+    // instead of failing — a warm laptop going offline shouldn't brick
+    // `tinycloud --help`. Pinned versions and strict mode still fail.
+    if (version === "latest" && process.env.TINYCLOUD_REQUIRE_MANIFEST !== "1") {
+      const fallback = findNewestHealthy(target);
+      if (fallback) {
+        process.stderr.write(
+          `tinycloud: could not resolve latest (${err.message.split("\n")[0]}); using cached ${fallback.version}\n`
+        );
+        return fallback;
+      }
+    }
+    throw err;
+  }
+}
+
+async function resolveAndInstall(version, target, opts = {}) {
+  const res = await resolveDownload(version, "stable", target, opts.manifest);
+  // Strict mode means verified-or-fail, not just manifest-present — same
+  // rule as install.sh (e.g. a manifest entry without sha256).
+  if (process.env.TINYCLOUD_REQUIRE_MANIFEST === "1" && !res.sha256) {
+    throw new Error(`TINYCLOUD_REQUIRE_MANIFEST=1 but no checksum is available for ${res.url}`);
+  }
+  // Manifest-sourced version strings become cache dir names too — run them
+  // through the same normalize/validate as user input.
+  if (res.version) res.version = normalizeVersion(res.version);
+  if (res.version) {
+    if (isInstalled(res.version, target)) return { dir: versionDir(res.version), version: res.version };
+  } else {
+    // "latest" with no manifest: the alias tarball has no version attached,
+    // but if its ETag matches a cached install of the same URL we can skip
+    // the ~90MB re-download.
+    const etag = await httpHeadEtag(res.url);
+    if (etag) {
+      const warm = findInstalledByUrlEtag(res.url, etag);
+      if (warm) return warm;
+    }
+  }
+
+  const root = rootDir();
+  fs.mkdirSync(path.join(root, "tmp"), { recursive: true });
+  const stage = fs.mkdtempSync(path.join(root, "tmp", "dl-"));
+  try {
+    const tarball = path.join(stage, "tinycloud.tar.gz");
+    process.stderr.write(`tinycloud: fetching ${res.url}\n`);
+    const { sha256: actual, etag } = await downloadWithHash(res.url, tarball);
+    if (res.sha256 && actual !== res.sha256.toLowerCase()) {
+      throw new Error(
+        `Checksum mismatch for ${res.url}\n  expected ${res.sha256}\n  actual   ${actual}\n` +
+          "Refusing to install. Retry, or report to Cloudglue if it persists."
+      );
+    }
+
+    const extracted = path.join(stage, "x");
+    fs.mkdirSync(extracted);
+    execFileSync("tar", ["-xzf", tarball, "-C", extracted]);
+    const binPath = path.join(extracted, "tinycloud");
+    if (!fs.existsSync(binPath)) throw new Error("Downloaded tarball is missing the ./tinycloud binary");
+
+    // Resolve "latest" with no manifest: ask the binary itself. stdin must be
+    // closed and the call bounded — pre-0.3.0 binaries open an interactive
+    // TUI on this invocation instead of printing JSON.
+    let version_ = res.version;
+    if (!version_) {
+      let out;
+      try {
+        out = execFileSync(binPath, ["--version", "--json"], {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"],
+          timeout: 15000,
+        });
+        version_ = JSON.parse(out).version;
+      } catch {
+        throw new Error(
+          "Downloaded binary did not report a machine-readable version (older than 0.3.0?) — refusing to install"
+        );
+      }
+      if (!version_) throw new Error("Downloaded binary reported no version — refusing to install");
+      version_ = normalizeVersion(version_); // binary-reported strings become dir names too
+    }
+
+    fs.writeFileSync(
+      path.join(extracted, ".ok"),
+      JSON.stringify({ version: version_, target, sha256: actual, verified: !!res.sha256, url: res.url, etag }) + "\n"
+    );
+    const dest = versionDir(version_);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    try {
+      fs.renameSync(extracted, dest);
+    } catch (err) {
+      // A peer's completed install only counts if it's for THIS platform —
+      // a wrong-platform extract under the same version is stale.
+      if (!isInstalled(version_, target)) {
+        if (fs.existsSync(dest)) {
+          // Leftover from an interrupted install (dir present, no .ok):
+          // clear it and claim the slot rather than failing forever. If a
+          // concurrent peer completes between the .ok check and this swap,
+          // we replace its install with our byte-identical extract of the
+          // same checksum-verified tarball — a momentary swap, not
+          // corruption (eliminating it entirely would need cross-process
+          // locking, which isn't worth it for this window).
+          fs.rmSync(dest, { recursive: true, force: true });
+          fs.renameSync(extracted, dest);
+        } else {
+          throw err;
+        }
+      }
+      // else: lost the race → another process completed the install
+    }
+    return { dir: dest, version: version_ };
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Keep the newest `keep` installed versions for THIS platform; remove the
+ * rest. Versions in `protect` (e.g. the one the wrapper currently resolves
+ * to) are never removed and don't count against `keep`. Broken entries (a
+ * .ok marker but no runnable binary) are removed outright and never occupy
+ * a retention slot. When `target` is given, healthy entries for OTHER
+ * platforms (a shared/synced cache root) are left untouched and don't
+ * count either — this machine's prune must not delete a peer machine's
+ * builds, nor let them crowd out the only build that runs here.
+ */
+function pruneVersions(keep = 2, protect = [], target) {
+  const dir = path.join(rootDir(), "versions");
+  const protected_ = new Set(protect.map(normalizeVersion).filter(Boolean));
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const healthy = [];
+  const broken = [];
+  for (const e of entries) {
+    // Dirs without .ok are crash leftovers; ensureInstalled reclaims those.
+    if (!fs.existsSync(path.join(dir, e, ".ok"))) continue;
+    if (protected_.has(e)) continue;
+    if (!isInstalled(e)) {
+      broken.push(e);
+      continue;
+    }
+    if (target && !isInstalled(e, target)) continue; // peer platform's tree
+    healthy.push(e);
+  }
+  healthy.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  const removed = [...broken, ...healthy.slice(0, Math.max(0, healthy.length - keep))];
+  for (const v of removed) fs.rmSync(path.join(dir, v), { recursive: true, force: true });
+  return removed;
+}
+
+module.exports = {
+  rootDir,
+  versionDir,
+  ensureInstalled,
+  pruneVersions,
+  readOverrideVersion,
+  writeOverrideVersion,
+  normalizeVersion,
+  isInstalled,
+};