cutsio 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# cutsio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Syncs Cutsio mezzanine masters to a local folder. Resumable, idempotent, and
+safe to run repeatedly: it downloads only videos that are new or changed since
+the last run.
+
+## Install
+
+```bash
+npm install -g cutsio     # then: cutsio sync …
+# or run without installing
+npx cutsio sync --out ~/Cutsio --collection vacation
+```
+
+Requires Node 18+ and `curl` on `PATH` (ships with macOS).
+
+Create an **organization** API key in Cutsio: Settings → Organization → API Keys.
+
+```bash
+cutsio login --url https://studio.cutsio.com --key ak_...
+cutsio whoami
+```
+
+Config is stored at `~/.cutsio/config.json` with mode `600`. You can also skip
+the config file entirely:
+
+```bash
+export CUTSIO_API_URL=https://studio.cutsio.com
+export CUTSIO_API_KEY=ak_...
+```
+
+## Development
+
+```bash
+npm install
+npm run dev -- whoami      # runs src/index.ts directly (Node 23.6+)
+npm run typecheck
+npm run build              # bundles src -> dist/index.js
+```
+
+## List and select
+
+`sync` never downloads the whole workspace unless you ask for it. Start by
+listing what's there:
+
+```bash
+cutsio list            # collections, folder paths, ids, and video counts
+cutsio list --videos   # every video with its id
+cutsio list --search shot   # title matches anywhere in the workspace
+cutsio list --json     # raw manifest
+```
+
+## Sync
+
+```bash
+cutsio sync --out ~/Cutsio --collection vacation
+cutsio sync --out ~/Cutsio --folder test/sub1a
+cutsio sync --out ~/Cutsio --all --dry-run
+cutsio sync --out ~/Cutsio --interactive
+```
+
+Selection flags are comma-separated and can be combined (the result is a union):
+
+| Flag | Meaning |
+|---|---|
+| `--all` | Every video in the workspace. Required for a full sync. |
+| `--folder <path\|id,...>` | A folder **and all of its subfolders**. |
+| `--collection <title\|id,...>` | Videos in a collection. |
+| `--video <id,...>` | Specific videos. |
+| `--search <term,...>` | Videos whose title contains a term, anywhere in the workspace. |
+| `--unfiled` | Videos that are in no folder. |
+| `--interactive` | Choose from a numbered menu. |
+
+Unknown or ambiguous selectors fail before anything is downloaded. Search also
+covers videos that are in no folder or collection.
+
+| Other flag | Default | Meaning |
+|---|---|---|
+| `--out <dir>` | `./cutsio` | Destination root. The folder tree is mirrored underneath. |
+| `--concurrency <n>` | `3` | Simultaneous downloads. |
+| `--max-wait <seconds>` | `600` | How long to wait for masters still preparing. |
+| `--limit <n>` | all | Cap how many videos this run downloads. |
+| `--dry-run` | off | Print what would download, change nothing. |
+
+## How it behaves
+
+- **Manifest diffing:** each video's `realtime_version` is stored in
+  `<out>/.cutsio-state.json`. A video is re-downloaded only when that version
+  changes or the local file is missing/short.
+- **Resume:** downloads go to `<file>.part` and `curl -C -` continues from the
+  existing byte offset. A crashed run picks up where it stopped, even if the
+  signed URL was refreshed in between.
+- **Expiring URLs:** Mux master URLs live 24h. On a failed transfer the CLI
+  re-prepares that single video once and retries.
+- **Nothing is deleted.** Videos removed upstream stay on disk; the CLI never
+  deletes local files.
+- **Filenames:** `<title> [<id8>].mp4` — the id suffix prevents collisions when
+  two videos share a title.
+- **Not ready / restricted:** videos that are still processing, or whose
+  moderation failed, are skipped and reported.
+
+## Build
+
+```bash
+npm run build      # esbuild bundle -> dist/index.js (published artifact)
+```
+
+`prepublishOnly` runs typecheck and build, so a stale `dist/` cannot be
+published.
+
+## Layout
+
+```
+src/index.ts          CLI entry and flag parsing
+src/commands/         login, whoami, list, sync, interactive picker
+src/core/client.ts    API client (manifest, prepare, whoami)
+src/core/selection.ts folder / collection / search selection
+src/core/sync.ts      diffing and orchestration
+src/core/download.ts  resumable curl-backed transfer
+src/core/paths.ts     folder tree -> local paths
+src/core/state.ts     versioned state file
+src/core/events.ts    structured progress events (the Tauri seam)
+```
+
+`src/core/` has no CLI-specific code. A Tauri app can bundle the compiled
+binary as a sidecar and render the same events, or the core can be ported
+without touching the orchestration logic.

package/dist/index.js

@@ -0,0 +1,1008 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import process2 from "node:process";
+
+// src/config.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var DEFAULT_API_URL = "https://studio.cutsio.com";
+function configPath() {
+  return join(homedir(), ".cutsio", "config.json");
+}
+function readConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed.apiUrl !== "string" || typeof parsed.apiKey !== "string") return null;
+    return { apiUrl: parsed.apiUrl, apiKey: parsed.apiKey };
+  } catch {
+    return null;
+  }
+}
+function writeConfig(config) {
+  const path = configPath();
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify(config, null, 2), { mode: 384 });
+  chmodSync(path, 384);
+}
+function resolveApiUrl(flag) {
+  return flag || process.env.CUTSIO_API_URL || readConfig()?.apiUrl || DEFAULT_API_URL;
+}
+function resolveApiKey() {
+  const key = process.env.CUTSIO_API_KEY || readConfig()?.apiKey;
+  return key && key.length > 0 ? key : null;
+}
+
+// src/core/client.ts
+var ApiError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+  }
+};
+var CutsioClient = class {
+  base;
+  apiKey;
+  constructor(apiUrl, apiKey) {
+    this.base = apiUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+  }
+  async whoami() {
+    return await this.request("/api/desktop/whoami");
+  }
+  async fetchManifest() {
+    let orgId = "";
+    let folders = [];
+    let collections = [];
+    const videos = [];
+    let cursor = null;
+    for (; ; ) {
+      const params = new URLSearchParams({ limit: "100" });
+      if (cursor !== null) params.set("cursor", String(cursor));
+      const page = await this.request(
+        `/api/desktop/manifest?${params.toString()}`
+      );
+      orgId = page.orgId;
+      folders = page.folders;
+      collections = page.collections ?? [];
+      videos.push(...page.videos);
+      if (!page.hasMore || page.nextCursor === null) break;
+      cursor = page.nextCursor;
+    }
+    return { orgId, folders, collections, videos };
+  }
+  async prepare(videoIds) {
+    const data = await this.request("/api/desktop/prepare", {
+      method: "POST",
+      body: JSON.stringify({ videoIds })
+    });
+    return Array.isArray(data.results) ? data.results : [];
+  }
+  async request(path, init) {
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...init?.body ? { "Content-Type": "application/json" } : {},
+      ...init?.headers ?? {}
+    };
+    const response = await fetch(`${this.base}${path}`, { ...init, headers });
+    if (!response.ok) {
+      let message = `HTTP ${response.status}`;
+      try {
+        const body = await response.json();
+        if (typeof body.error === "string") message = body.error;
+      } catch {
+      }
+      throw new ApiError(message, response.status);
+    }
+    return response.json();
+  }
+};
+
+// src/core/paths.ts
+function sanitizeSegment(value) {
+  const cleaned = value.replace(/[/\\?%*:|"<>]/g, "-").replace(/\s+/g, " ").replace(/^[.\s]+|[.\s]+$/g, "").slice(0, 80).trim();
+  return cleaned.length > 0 ? cleaned : "untitled";
+}
+function buildFolderPaths(folders) {
+  const byId = new Map(folders.map((folder) => [folder.id, folder]));
+  const memo = /* @__PURE__ */ new Map();
+  const resolve = (id, seen) => {
+    const cached = memo.get(id);
+    if (cached !== void 0) return cached;
+    const folder = byId.get(id);
+    if (!folder || seen.has(id)) return "";
+    seen.add(id);
+    const parent = folder.parent_id ? resolve(folder.parent_id, seen) : "";
+    const path = parent ? `${parent}/${sanitizeSegment(folder.name)}` : sanitizeSegment(folder.name);
+    memo.set(id, path);
+    return path;
+  };
+  for (const folder of folders) resolve(folder.id, /* @__PURE__ */ new Set());
+  return memo;
+}
+function videoRelativePath(video, folderPaths) {
+  const directory = video.folder_id ? folderPaths.get(video.folder_id) ?? "" : "";
+  const name = `${sanitizeSegment(video.title)} [${video.id.slice(0, 8)}].mp4`;
+  return directory ? `${directory}/${name}` : name;
+}
+
+// src/core/selection.ts
+function isEmptySelection(selection) {
+  return !selection.all && !selection.unfiled && selection.folderRefs.length === 0 && selection.collectionRefs.length === 0 && selection.videoIds.length === 0 && selection.searchTerms.length === 0;
+}
+function folderSubtreeIds(manifest) {
+  const children = /* @__PURE__ */ new Map();
+  for (const folder of manifest.folders) {
+    if (!folder.parent_id) continue;
+    const list = children.get(folder.parent_id) ?? [];
+    list.push(folder.id);
+    children.set(folder.parent_id, list);
+  }
+  const subtrees = /* @__PURE__ */ new Map();
+  for (const folder of manifest.folders) {
+    const ids = /* @__PURE__ */ new Set([folder.id]);
+    const stack = [folder.id];
+    for (; ; ) {
+      const id = stack.pop();
+      if (id === void 0) break;
+      for (const child of children.get(id) ?? []) {
+        if (ids.has(child)) continue;
+        ids.add(child);
+        stack.push(child);
+      }
+    }
+    subtrees.set(folder.id, ids);
+  }
+  return subtrees;
+}
+function folderVideoCounts(manifest) {
+  const subtrees = folderSubtreeIds(manifest);
+  const direct = /* @__PURE__ */ new Map();
+  const subtree = /* @__PURE__ */ new Map();
+  for (const video of manifest.videos) {
+    if (!video.folder_id) continue;
+    direct.set(video.folder_id, (direct.get(video.folder_id) ?? 0) + 1);
+  }
+  for (const [folderId, ids] of subtrees) {
+    let count = 0;
+    for (const video of manifest.videos) {
+      if (video.folder_id && ids.has(video.folder_id)) count += 1;
+    }
+    subtree.set(folderId, count);
+  }
+  return { direct, subtree };
+}
+function resolveSelection(manifest, selection) {
+  if (selection.all) return { videos: manifest.videos, errors: [] };
+  const errors = [];
+  const selected = /* @__PURE__ */ new Map();
+  const folderPaths = buildFolderPaths(manifest.folders);
+  const pathIndex = /* @__PURE__ */ new Map();
+  for (const [id, path] of folderPaths) pathIndex.set(path.toLowerCase(), id);
+  const nameIndex = /* @__PURE__ */ new Map();
+  for (const folder of manifest.folders) {
+    const key = folder.name.toLowerCase();
+    nameIndex.set(key, [...nameIndex.get(key) ?? [], folder.id]);
+  }
+  const resolveFolder = (ref) => {
+    if (folderPaths.has(ref)) return ref;
+    const byPath = pathIndex.get(ref.toLowerCase());
+    if (byPath) return byPath;
+    const byName = nameIndex.get(ref.toLowerCase());
+    if (byName && byName.length === 1) return byName[0] ?? null;
+    return null;
+  };
+  const subtrees = folderSubtreeIds(manifest);
+  const folderIds = /* @__PURE__ */ new Set();
+  for (const ref of selection.folderRefs) {
+    const id = resolveFolder(ref);
+    if (!id) {
+      const byName = nameIndex.get(ref.toLowerCase());
+      errors.push(
+        byName && byName.length > 1 ? `Folder name is ambiguous: ${ref} (use the path or id)` : `Folder not found: ${ref}`
+      );
+      continue;
+    }
+    for (const descendant of subtrees.get(id) ?? [id]) folderIds.add(descendant);
+  }
+  if (folderIds.size > 0) {
+    for (const video of manifest.videos) {
+      if (video.folder_id && folderIds.has(video.folder_id)) selected.set(video.id, video);
+    }
+  }
+  const collectionIds = /* @__PURE__ */ new Set();
+  for (const ref of selection.collectionRefs) {
+    const matches = manifest.collections.filter(
+      (collection) => collection.id === ref || collection.title.toLowerCase() === ref.toLowerCase()
+    );
+    if (matches.length === 0) {
+      errors.push(`Collection not found: ${ref}`);
+      continue;
+    }
+    for (const collection of matches) collectionIds.add(collection.id);
+  }
+  if (collectionIds.size > 0) {
+    for (const video of manifest.videos) {
+      if (video.collection_id && collectionIds.has(video.collection_id)) selected.set(video.id, video);
+    }
+  }
+  const byId = new Map(manifest.videos.map((video) => [video.id, video]));
+  for (const id of selection.videoIds) {
+    const video = byId.get(id);
+    if (!video) {
+      errors.push(`Video not found: ${id}`);
+      continue;
+    }
+    selected.set(video.id, video);
+  }
+  if (selection.unfiled) {
+    for (const video of manifest.videos) {
+      if (!video.folder_id) selected.set(video.id, video);
+    }
+  }
+  for (const term of selection.searchTerms) {
+    const needle = term.toLowerCase();
+    let matches = 0;
+    for (const video of manifest.videos) {
+      if (!video.title.toLowerCase().includes(needle)) continue;
+      selected.set(video.id, video);
+      matches += 1;
+    }
+    if (matches === 0) errors.push(`No video titles match: ${term}`);
+  }
+  return { videos: [...selected.values()], errors };
+}
+
+// src/commands/list.ts
+async function listCommand(flags) {
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error("No API key. Run `cutsio login` or set CUTSIO_API_KEY.");
+    return 1;
+  }
+  const client = new CutsioClient(resolveApiUrl(flags.url), apiKey);
+  let manifest;
+  try {
+    manifest = await client.fetchManifest();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+  if (flags.json === "true") {
+    console.log(JSON.stringify(manifest, null, 2));
+    return 0;
+  }
+  const search = (flags.search ?? "").trim().toLowerCase();
+  if (search) {
+    const matches = manifest.videos.filter((video) => video.title.toLowerCase().includes(search));
+    console.log(`Title matches (${matches.length}) for "${flags.search}":`);
+    if (matches.length === 0) console.log("  (none)");
+    for (const video of matches) {
+      console.log(`  [${video.id}]  ${video.status.padEnd(10)}  ${video.title}`);
+    }
+    return 0;
+  }
+  const folderPaths = buildFolderPaths(manifest.folders);
+  const { subtree } = folderVideoCounts(manifest);
+  console.log(`Collections (${manifest.collections.length}) \u2014 select with --collection <name|id>`);
+  if (manifest.collections.length === 0) console.log("  (none)");
+  for (const collection of manifest.collections) {
+    const count = manifest.videos.filter((video) => video.collection_id === collection.id).length;
+    console.log(`  ${pad(count)}  ${collection.title}  [${collection.id}]`);
+  }
+  console.log(`
+Folders (${manifest.folders.length}) \u2014 select with --folder <path|id>`);
+  if (manifest.folders.length === 0) console.log("  (none)");
+  const rows = [...folderPaths.entries()].sort((a, b) => a[1].localeCompare(b[1]));
+  for (const [id, path] of rows) {
+    console.log(`  ${pad(subtree.get(id) ?? 0)}  ${path}/  [${id}]`);
+  }
+  const unfiled = manifest.videos.filter((video) => !video.folder_id).length;
+  if (unfiled > 0) console.log(`  ${pad(unfiled)}  (no folder)`);
+  if (flags.videos === "true") {
+    console.log(`
+Videos (${manifest.videos.length}) \u2014 select with --video <id>`);
+    for (const video of manifest.videos) {
+      console.log(`  [${video.id}]  ${video.status.padEnd(10)}  ${video.title}`);
+    }
+  }
+  return 0;
+}
+function pad(count) {
+  return `${count} video${count === 1 ? " " : "s"}`.padStart(9);
+}
+
+// src/commands/login.ts
+import { stdin, stdout } from "node:process";
+var MAX_ATTEMPTS = 3;
+var KEY_PATTERN = /^ak_[A-Za-z0-9]{20,}$/;
+async function loginCommand(flags) {
+  const apiUrl = resolveApiUrl(flags.url);
+  const interactiveTty = Boolean(stdin.isTTY) && typeof stdin.setRawMode === "function";
+  console.log(`Signing in to ${apiUrl}`);
+  console.log("Create an organization API key in Cutsio (Account or Organization \u2192 API Keys).");
+  console.log("The secret is shown once, when you create the key.\n");
+  const pipedAnswers = interactiveTty ? null : await readPipedAnswers();
+  let pipedIndex = 0;
+  let fromFlag = flags.key;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+    let raw;
+    if (fromFlag !== void 0) {
+      raw = fromFlag;
+      fromFlag = void 0;
+    } else if (pipedAnswers) {
+      const next = pipedAnswers[pipedIndex];
+      pipedIndex += 1;
+      if (next === void 0) break;
+      raw = next;
+    } else {
+      raw = await promptSecret("Paste API key: ");
+    }
+    const apiKey = normalizeKey(raw);
+    if (!apiKey) {
+      console.error("No API key entered.\n");
+      continue;
+    }
+    if (!KEY_PATTERN.test(apiKey)) {
+      console.error('That does not look like a Cutsio API key (expected something starting with "ak_").\n');
+      continue;
+    }
+    try {
+      const who = await new CutsioClient(apiUrl, apiKey).whoami();
+      if (!who.orgId) {
+        console.error("That key is not attached to an organization. Create an organization API key.\n");
+        continue;
+      }
+      writeConfig({ apiUrl, apiKey });
+      console.log(`
+Saved. Organization ${who.orgId}${who.name ? ` (key "${who.name}")` : ""}.`);
+      console.log(`Config: ${configPath()}
+`);
+      console.log("Next:");
+      console.log("  cutsio list");
+      console.log("  cutsio sync --out ~/Cutsio --interactive");
+      return 0;
+    } catch (error) {
+      console.error(`${explain(error, apiUrl)}
+`);
+    }
+  }
+  console.error("Could not authenticate. Nothing was saved.");
+  return 1;
+}
+async function readPipedAnswers() {
+  const chunks = [];
+  for await (const chunk of stdin) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8").split(/\r?\n/);
+}
+function normalizeKey(raw) {
+  let value = raw.trim();
+  const quoted = value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'");
+  if (quoted && value.length > 1) {
+    value = value.slice(1, -1).trim();
+  }
+  return value.replace(/^bearer\s+/i, "").trim();
+}
+function explain(error, apiUrl) {
+  if (error instanceof ApiError) {
+    if (error.status === 401) {
+      return [
+        "That key was rejected.",
+        "  - If you copied it from the key list, that is the key ID, not the secret.",
+        "    The secret is only shown once at creation \u2014 create a new key.",
+        `  - If it was created in a different environment than ${apiUrl}, it will not exist here.`
+      ].join("\n");
+    }
+    if (error.status === 403) {
+      return `That key authenticated but has no organization. ${error.message}`;
+    }
+    return `The server rejected the key (HTTP ${error.status}): ${error.message}`;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return `Could not reach ${apiUrl}: ${message}`;
+}
+async function promptSecret(question) {
+  stdout.write(question);
+  stdin.setRawMode?.(true);
+  stdin.resume();
+  stdin.setEncoding("utf8");
+  return new Promise((resolve) => {
+    let value = "";
+    const finish = () => {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdin.off("data", onData);
+      stdout.write("\n");
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const char of chunk) {
+        if (char === "\r" || char === "\n" || char === "") {
+          finish();
+          return;
+        }
+        if (char === "") {
+          stdin.setRawMode?.(false);
+          stdout.write("\n");
+          process.exit(130);
+        }
+        if (char === "\x7F" || char === "\b") {
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+            stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (char < " ") continue;
+        value += char;
+        stdout.write("*");
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+// src/core/sync.ts
+import { existsSync as existsSync4, statSync as statSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/core/download.ts
+import { spawn } from "node:child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync, statSync } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+function partPathFor(destPath) {
+  return `${destPath}.part`;
+}
+async function downloadResumable(url, destPath) {
+  mkdirSync2(dirname2(destPath), { recursive: true });
+  const part = partPathFor(destPath);
+  const resumedFrom = existsSync2(part) ? statSync(part).size : 0;
+  const { code, stderr } = await runCurl([
+    "-sS",
+    "--fail",
+    "--location",
+    "--retry",
+    "5",
+    "--retry-delay",
+    "2",
+    "--retry-all-errors",
+    "--connect-timeout",
+    "30",
+    "-C",
+    "-",
+    "-o",
+    part,
+    url
+  ]);
+  if (code === 0) {
+    renameSync(part, destPath);
+    return { ok: true, bytes: statSync(destPath).size, resumedFrom };
+  }
+  const remote = await remoteSize(url);
+  if (remote !== null && existsSync2(part) && statSync(part).size === remote) {
+    renameSync(part, destPath);
+    return { ok: true, bytes: remote, resumedFrom };
+  }
+  const lastLine = stderr.trim().split("\n").filter(Boolean).at(-1);
+  return { ok: false, error: `curl exited ${code}${lastLine ? `: ${lastLine}` : ""}` };
+}
+function runCurl(args) {
+  return new Promise((resolve) => {
+    const child = spawn("curl", args, { stdio: ["ignore", "ignore", "pipe"] });
+    let stderr = "";
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("error", (error) => resolve({ code: -1, stderr: error.message }));
+    child.on("close", (code) => resolve({ code: code ?? -1, stderr }));
+  });
+}
+async function remoteSize(url) {
+  try {
+    const response = await fetch(url, { method: "HEAD" });
+    if (!response.ok) return null;
+    const header = response.headers.get("content-length");
+    const value = header ? Number(header) : Number.NaN;
+    return Number.isFinite(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+// src/core/state.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync2, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname3 } from "node:path";
+var STATE_FILE = ".cutsio-state.json";
+var StateOrgMismatchError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "StateOrgMismatchError";
+  }
+};
+function emptyState(orgId) {
+  return { schema: 1, orgId, updatedAt: Date.now(), videos: {} };
+}
+function loadState(path, orgId) {
+  if (!existsSync3(path)) return emptyState(orgId);
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    if (parsed.schema !== 1 || typeof parsed.videos !== "object" || parsed.videos === null) {
+      return emptyState(orgId);
+    }
+    if (parsed.orgId && parsed.orgId !== orgId) {
+      throw new StateOrgMismatchError(
+        `This directory is already syncing ${parsed.orgId}. Use a different --out directory for ${orgId}.`
+      );
+    }
+    return { schema: 1, orgId, updatedAt: Date.now(), videos: parsed.videos };
+  } catch (error) {
+    if (error instanceof StateOrgMismatchError) throw error;
+    return emptyState(orgId);
+  }
+}
+function saveState(path, state) {
+  mkdirSync3(dirname3(path), { recursive: true });
+  state.updatedAt = Date.now();
+  const temp = `${path}.tmp`;
+  writeFileSync2(temp, JSON.stringify(state, null, 2));
+  renameSync2(temp, path);
+}
+
+// src/core/sync.ts
+var PREPARE_BATCH_SIZE = 50;
+var INITIAL_PREPARE_DELAY_MS = 3e3;
+var MAX_PREPARE_DELAY_MS = 3e4;
+async function sync(client, options) {
+  const { onEvent, outDir } = options;
+  const manifest = options.manifest ?? await client.fetchManifest();
+  const resolved = resolveSelection(manifest, options.selection);
+  if (resolved.errors.length > 0) {
+    throw new Error(`Selection problems:
+  ${resolved.errors.join("\n  ")}`);
+  }
+  if (resolved.videos.length === 0) {
+    throw new Error("Selection matched no videos.");
+  }
+  const folderPaths = buildFolderPaths(manifest.folders);
+  const statePath = join2(outDir, STATE_FILE);
+  const state = loadState(statePath, manifest.orgId);
+  onEvent({
+    type: "manifest",
+    orgId: manifest.orgId,
+    folders: manifest.folders.length,
+    videos: manifest.videos.length
+  });
+  const pending = [];
+  let unchanged = 0;
+  let skipped = 0;
+  for (const video of resolved.videos) {
+    if (video.status !== "ready") {
+      skipped += 1;
+      onEvent({ type: "file-skipped", id: video.id, title: video.title, reason: `status: ${video.status}` });
+      continue;
+    }
+    if (video.moderation_status === "failed" || video.moderation_status === "errored") {
+      skipped += 1;
+      onEvent({ type: "file-skipped", id: video.id, title: video.title, reason: "restricted" });
+      continue;
+    }
+    const relPath = videoRelativePath(video, folderPaths);
+    const absPath = join2(outDir, relPath);
+    const stored = state.videos[video.id];
+    const isCurrent = stored !== void 0 && stored.version === video.version && stored.path === relPath && existsSync4(absPath) && (stored.sizeBytes === null || statSync2(absPath).size === stored.sizeBytes);
+    if (isCurrent) {
+      unchanged += 1;
+      continue;
+    }
+    pending.push({ video, absPath, relPath, resuming: existsSync4(partPathFor(absPath)) });
+  }
+  const selected = options.limit && options.limit > 0 ? pending.slice(0, options.limit) : pending;
+  onEvent({ type: "planned", total: resolved.videos.length, pending: selected.length, unchanged });
+  if (options.dryRun) {
+    for (const item of selected) {
+      onEvent({
+        type: "file-start",
+        id: item.video.id,
+        title: item.video.title,
+        path: item.relPath,
+        resuming: item.resuming
+      });
+    }
+    return { downloaded: 0, unchanged, skipped, failed: 0 };
+  }
+  let downloaded = 0;
+  let failed = 0;
+  let prepareDelayMs = INITIAL_PREPARE_DELAY_MS;
+  const deadline = Date.now() + options.maxWaitSeconds * 1e3;
+  const queue = new Map(selected.map((item) => [item.video.id, item]));
+  while (queue.size > 0) {
+    const ready = [];
+    const ids = [...queue.keys()];
+    for (let index = 0; index < ids.length; index += PREPARE_BATCH_SIZE) {
+      const batch = ids.slice(index, index + PREPARE_BATCH_SIZE);
+      const results = await client.prepare(batch);
+      for (const result of results) {
+        const item = queue.get(result.id);
+        if (!item) continue;
+        switch (result.status) {
+          case "ready":
+            if (result.url) {
+              ready.push({ id: result.id, url: result.url });
+            } else {
+              queue.delete(result.id);
+              failed += 1;
+              onEvent({ type: "file-failed", id: result.id, title: item.video.title, error: "no download URL returned" });
+            }
+            break;
+          case "preparing":
+            break;
+          case "not_found":
+          case "not_ready":
+            queue.delete(result.id);
+            skipped += 1;
+            onEvent({ type: "file-skipped", id: result.id, title: item.video.title, reason: result.status });
+            break;
+          case "forbidden":
+            queue.delete(result.id);
+            skipped += 1;
+            onEvent({ type: "file-skipped", id: result.id, title: item.video.title, reason: "restricted" });
+            break;
+          default:
+            queue.delete(result.id);
+            failed += 1;
+            onEvent({ type: "file-failed", id: result.id, title: item.video.title, error: `prepare: ${result.status}` });
+            break;
+        }
+      }
+    }
+    if (ready.length > 0) {
+      prepareDelayMs = INITIAL_PREPARE_DELAY_MS;
+      await runPool(ready, options.concurrency, async ({ id, url }) => {
+        const item = queue.get(id);
+        if (!item) return;
+        onEvent({
+          type: "file-start",
+          id,
+          title: item.video.title,
+          path: item.relPath,
+          resuming: item.resuming
+        });
+        let result = await downloadResumable(url, item.absPath);
+        if (!result.ok) {
+          const [refreshed] = await client.prepare([id]);
+          if (refreshed?.status === "ready" && refreshed.url) {
+            result = await downloadResumable(refreshed.url, item.absPath);
+          }
+        }
+        if (result.ok) {
+          state.videos[id] = {
+            version: item.video.version,
+            sizeBytes: result.bytes,
+            path: item.relPath
+          };
+          saveState(statePath, state);
+          queue.delete(id);
+          downloaded += 1;
+          onEvent({ type: "file-done", id, title: item.video.title, path: item.relPath, bytes: result.bytes });
+        } else {
+          queue.delete(id);
+          failed += 1;
+          onEvent({ type: "file-failed", id, title: item.video.title, error: result.error });
+        }
+      });
+    }
+    if (queue.size === 0) break;
+    if (Date.now() > deadline) {
+      for (const item of queue.values()) {
+        failed += 1;
+        onEvent({
+          type: "file-failed",
+          id: item.video.id,
+          title: item.video.title,
+          error: "timed out waiting for the master"
+        });
+      }
+      break;
+    }
+    await sleep(prepareDelayMs);
+    prepareDelayMs = Math.min(prepareDelayMs * 2, MAX_PREPARE_DELAY_MS);
+  }
+  return { downloaded, unchanged, skipped, failed };
+}
+async function runPool(items, concurrency, worker) {
+  let index = 0;
+  const workerCount = Math.max(1, Math.min(concurrency, items.length));
+  await Promise.all(
+    Array.from({ length: workerCount }, async () => {
+      for (; ; ) {
+        const current = index;
+        index += 1;
+        const item = items[current];
+        if (item === void 0) return;
+        await worker(item);
+      }
+    })
+  );
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/commands/selection-prompt.ts
+import { stdin as stdin2, stdout as stdout2 } from "node:process";
+import { createInterface } from "node:readline/promises";
+function countLabel(count) {
+  return `${count} video${count === 1 ? "" : "s"}`;
+}
+async function promptSelection(manifest) {
+  const { subtree } = folderVideoCounts(manifest);
+  const entries = [
+    ...manifest.collections.map((collection) => ({
+      kind: "collection",
+      ref: collection.title,
+      label: `collection ${collection.title} \u2014 ${countLabel(
+        manifest.videos.filter((video) => video.collection_id === collection.id).length
+      )}`
+    })),
+    ...[...buildFolderPaths(manifest.folders).entries()].sort((a, b) => a[1].localeCompare(b[1])).map(([id, path]) => ({
+      kind: "folder",
+      ref: path,
+      label: `folder ${path}/ \u2014 ${countLabel(subtree.get(id) ?? 0)}`
+    }))
+  ];
+  const unfiledCount = manifest.videos.filter((video) => !video.folder_id).length;
+  if (unfiledCount > 0) {
+    entries.push({
+      kind: "unfiled",
+      ref: "",
+      label: `unfiled (no folder) \u2014 ${countLabel(unfiledCount)}`
+    });
+  }
+  if (entries.length === 0) {
+    console.error("Nothing to select: this workspace has no folders or collections.");
+    return null;
+  }
+  console.log("Select what to sync:");
+  entries.forEach((entry, index) => {
+    console.log(`  ${String(index + 1).padStart(3)}) ${entry.label}`);
+  });
+  const rl = createInterface({ input: stdin2, output: stdout2 });
+  try {
+    for (; ; ) {
+      const answer = (await rl.question('Numbers separated by commas, "all", or blank to cancel: ')).trim();
+      if (answer === "") return null;
+      if (answer.toLowerCase() === "all") {
+        return { all: true, unfiled: false, folderRefs: [], collectionRefs: [], videoIds: [], searchTerms: [] };
+      }
+      const indexes = answer.split(/[,\s]+/).filter(Boolean).map(Number);
+      const invalid = indexes.some(
+        (value) => !Number.isInteger(value) || value < 1 || value > entries.length
+      );
+      if (invalid || indexes.length === 0) {
+        console.log(`Enter numbers between 1 and ${entries.length}.`);
+        continue;
+      }
+      const picked = indexes.map((index) => entries[index - 1]).filter((entry) => entry !== void 0);
+      return {
+        all: false,
+        unfiled: picked.some((entry) => entry.kind === "unfiled"),
+        folderRefs: picked.filter((entry) => entry.kind === "folder").map((entry) => entry.ref),
+        collectionRefs: picked.filter((entry) => entry.kind === "collection").map((entry) => entry.ref),
+        videoIds: [],
+        searchTerms: []
+      };
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/sync.ts
+async function syncCommand(flags) {
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error("No API key. Run `cutsio login` or set CUTSIO_API_KEY.");
+    return 1;
+  }
+  const client = new CutsioClient(resolveApiUrl(flags.url), apiKey);
+  const onEvent = (event) => {
+    switch (event.type) {
+      case "manifest":
+        console.log(`Manifest: ${event.videos} videos, ${event.folders} folders (${event.orgId})`);
+        break;
+      case "planned":
+        console.log(`Selected ${event.total}, pending ${event.pending}, unchanged ${event.unchanged}`);
+        break;
+      case "file-start":
+        console.log(`  ${event.resuming ? "resume " : "fetch  "} ${event.path}`);
+        break;
+      case "file-done":
+        console.log(`  done    ${event.path} (${formatBytes(event.bytes)})`);
+        break;
+      case "file-skipped":
+        console.log(`  skip    ${event.title} \u2014 ${event.reason}`);
+        break;
+      case "file-failed":
+        console.error(`  FAILED  ${event.title} \u2014 ${event.error}`);
+        break;
+      case "warning":
+        console.warn(`warning: ${event.message}`);
+        break;
+    }
+  };
+  let selection = {
+    all: flags.all === "true",
+    folderRefs: splitList(flags.folder),
+    collectionRefs: splitList(flags.collection),
+    videoIds: splitList(flags.video),
+    searchTerms: splitList(flags.search),
+    unfiled: flags.unfiled === "true"
+  };
+  let manifest;
+  try {
+    if (flags.interactive === "true") {
+      manifest = await client.fetchManifest();
+      const prompted = await promptSelection(manifest);
+      if (!prompted) {
+        console.log("Cancelled. Nothing downloaded.");
+        return 0;
+      }
+      selection = mergeSelections(selection, prompted);
+    }
+    if (isEmptySelection(selection)) {
+      console.error("Refusing to sync the whole workspace. Choose one of:\n");
+      console.error("  --all                        every video in the workspace");
+      console.error("  --folder <path|id,...>       a folder and everything under it");
+      console.error("  --collection <name|id,...>   a collection");
+      console.error("  --video <id,...>             specific videos");
+      console.error("  --search <term,...>          video titles containing a term");
+      console.error("  --unfiled                    videos that are in no folder");
+      console.error("  --interactive                pick from a menu\n");
+      console.error("`cutsio list` prints names, paths, and ids.");
+      return 1;
+    }
+    const summary = await sync(client, {
+      outDir: flags.out ?? "./cutsio",
+      concurrency: positiveInt(flags.concurrency, 3),
+      dryRun: flags["dry-run"] === "true",
+      maxWaitSeconds: positiveInt(flags["max-wait"], 600),
+      limit: positiveInt(flags.limit, 0),
+      selection,
+      manifest,
+      onEvent
+    });
+    console.log(
+      `
+Downloaded ${summary.downloaded}, unchanged ${summary.unchanged}, skipped ${summary.skipped}, failed ${summary.failed}.`
+    );
+    return summary.failed > 0 ? 1 : 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+function splitList(value) {
+  if (!value) return [];
+  return [...new Set(value.split(",").map((entry) => entry.trim()).filter(Boolean))];
+}
+function mergeSelections(a, b) {
+  return {
+    all: a.all || b.all,
+    unfiled: a.unfiled || b.unfiled,
+    folderRefs: [.../* @__PURE__ */ new Set([...a.folderRefs, ...b.folderRefs])],
+    collectionRefs: [.../* @__PURE__ */ new Set([...a.collectionRefs, ...b.collectionRefs])],
+    videoIds: [.../* @__PURE__ */ new Set([...a.videoIds, ...b.videoIds])],
+    searchTerms: [.../* @__PURE__ */ new Set([...a.searchTerms, ...b.searchTerms])]
+  };
+}
+function positiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+function formatBytes(bytes) {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${value.toFixed(unit === 0 ? 0 : 1)} ${units[unit]}`;
+}
+
+// src/commands/whoami.ts
+async function whoamiCommand(flags) {
+  const apiKey = resolveApiKey();
+  if (!apiKey) {
+    console.error("No API key. Run `cutsio login` or set CUTSIO_API_KEY.");
+    return 1;
+  }
+  const client = new CutsioClient(resolveApiUrl(flags.url), apiKey);
+  try {
+    console.log(JSON.stringify(await client.whoami(), null, 2));
+    return 0;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+
+// src/index.ts
+function parseFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg || !arg.startsWith("--")) continue;
+    const body = arg.slice(2);
+    const separator = body.indexOf("=");
+    const key = separator === -1 ? body : body.slice(0, separator);
+    const inline = separator === -1 ? void 0 : body.slice(separator + 1);
+    if (!key) continue;
+    if (inline !== void 0) {
+      flags[key] = inline;
+      continue;
+    }
+    const next = args[index + 1];
+    if (next !== void 0 && !next.startsWith("--")) {
+      flags[key] = next;
+      index += 1;
+    } else {
+      flags[key] = "true";
+    }
+  }
+  return flags;
+}
+function printHelp() {
+  console.log(`cutsio \u2014 sync Cutsio mezzanine masters to a local folder
+
+Usage:
+  cutsio login [--url URL] [--key KEY]
+  cutsio whoami [--url URL]
+  cutsio list [--videos] [--search TERM] [--json] [--url URL]
+  cutsio sync [--all | --folder REFS | --collection REFS | --video IDS | --search TERMS | --unfiled | --interactive]
+              [--out DIR] [--concurrency N] [--max-wait SECONDS] [--limit N] [--dry-run] [--url URL]
+
+Selection:
+  REFS and IDS are comma-separated. Folders accept a path (e.g. test/sub1a) or id;
+  collections accept a title or id. A folder selection includes its subfolders.
+  --search matches video titles anywhere in the workspace; --unfiled selects
+  videos that are in no folder.
+
+Environment:
+  CUTSIO_API_URL   API base URL (default ${DEFAULT_API_URL})
+  CUTSIO_API_KEY   Organization API key`);
+}
+async function main() {
+  const [, , command, ...rest] = process2.argv;
+  const flags = parseFlags(rest);
+  switch (command) {
+    case "login":
+      return loginCommand(flags);
+    case "whoami":
+      return whoamiCommand(flags);
+    case "list":
+      return listCommand(flags);
+    case "sync":
+      return syncCommand(flags);
+    case void 0:
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      return 0;
+    default:
+      console.error(`Unknown command: ${command}`);
+      printHelp();
+      return 1;
+  }
+}
+main().then((code) => {
+  process2.exitCode = code;
+});

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "cutsio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Sync Cutsio mezzanine masters to a local folder",
+  "type": "module",
+  "bin": {
+    "cutsio": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "cutsio",
+    "cli",
+    "download",
+    "sync",
+    "mux",
+    "mezzanine"
+  ],
+  "scripts": {
+    "dev": "node src/index.ts",
+    "start": "node dist/index.js",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "esbuild": "^0.24.0",
+    "typescript": "^5.7.2"
+  }
+}