cutsio 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +132 -2
  2. package/dist/index.js +1375 -0
  3. package/package.json +35 -4
package/README.md CHANGED
@@ -1,3 +1,133 @@
1
- # Temporary Holding Version
1
+ # cutsio
2
2
 
3
- 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.
3
+ Syncs Cutsio mezzanine masters to a local folder. Resumable, idempotent, and
4
+ safe to run repeatedly: it downloads only videos that are new or changed since
5
+ the last run.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install -g cutsio # then: cutsio sync …
11
+ # or run without installing
12
+ npx cutsio sync --out ~/Cutsio --collection vacation
13
+ ```
14
+
15
+ Requires Node 18+ and `curl` on `PATH` (ships with macOS).
16
+
17
+ Create an **organization** API key in Cutsio: Settings → Organization → API Keys.
18
+
19
+ ```bash
20
+ cutsio login --url https://studio.cutsio.com --key ak_...
21
+ cutsio whoami
22
+ cutsio logout # removes the stored key
23
+ ```
24
+
25
+ On macOS the key goes into the **Keychain**; elsewhere it is written to
26
+ `~/.cutsio/config.json` with mode `600`. You can also skip the config file
27
+ entirely:
28
+
29
+ ```bash
30
+ export CUTSIO_API_URL=https://studio.cutsio.com
31
+ export CUTSIO_API_KEY=ak_...
32
+ ```
33
+
34
+ ## Development
35
+
36
+ ```bash
37
+ npm install
38
+ npm run dev -- whoami # runs src/index.ts directly (Node 23.6+)
39
+ npm run typecheck
40
+ npm test # selection, paths, and state
41
+ npm run build # bundles src -> dist/index.js
42
+ ```
43
+
44
+ Set `NO_COLOR=1` to disable color and `CUTSIO_NO_ANIM=1` to disable the
45
+ first-run banner and live progress. Both are automatic when output is piped.
46
+
47
+ ## List and select
48
+
49
+ `sync` never downloads the whole workspace unless you ask for it. Start by
50
+ listing what's there:
51
+
52
+ ```bash
53
+ cutsio list # collections, folder paths, ids, and video counts
54
+ cutsio list --videos # every video with its id
55
+ cutsio list --search shot # title matches anywhere in the workspace
56
+ cutsio list --json # raw manifest
57
+ ```
58
+
59
+ ## Sync
60
+
61
+ ```bash
62
+ cutsio sync --out ~/Cutsio --collection vacation
63
+ cutsio sync --out ~/Cutsio --folder test/sub1a
64
+ cutsio sync --out ~/Cutsio --all --dry-run
65
+ cutsio sync --out ~/Cutsio --interactive
66
+ ```
67
+
68
+ Selection flags are comma-separated and can be combined (the result is a union):
69
+
70
+ | Flag | Meaning |
71
+ |---|---|
72
+ | `--all` | Every video in the workspace. Required for a full sync. |
73
+ | `--folder <path\|id,...>` | A folder **and all of its subfolders**. |
74
+ | `--collection <title\|id,...>` | Videos in a collection. |
75
+ | `--video <id,...>` | Specific videos. |
76
+ | `--search <term,...>` | Videos whose title contains a term, anywhere in the workspace. |
77
+ | `--unfiled` | Videos that are in no folder. |
78
+ | `--interactive` | Choose from a numbered menu. |
79
+
80
+ Unknown or ambiguous selectors fail before anything is downloaded. Search also
81
+ covers videos that are in no folder or collection.
82
+
83
+ | Other flag | Default | Meaning |
84
+ |---|---|---|
85
+ | `--out <dir>` | `./cutsio` | Destination root. The folder tree is mirrored underneath. |
86
+ | `--concurrency <n>` | `3` | Simultaneous downloads. |
87
+ | `--max-wait <seconds>` | `600` | How long to wait for masters still preparing. |
88
+ | `--limit <n>` | all | Cap how many videos this run downloads. |
89
+ | `--dry-run` | off | Print what would download, change nothing. |
90
+
91
+ ## How it behaves
92
+
93
+ - **Manifest diffing:** each video's `realtime_version` is stored in
94
+ `<out>/.cutsio-state.json`. A video is re-downloaded only when that version
95
+ changes or the local file is missing/short.
96
+ - **Resume:** downloads go to `<file>.part` and `curl -C -` continues from the
97
+ existing byte offset. A crashed run picks up where it stopped, even if the
98
+ signed URL was refreshed in between.
99
+ - **Expiring URLs:** Mux master URLs live 24h. On a failed transfer the CLI
100
+ re-prepares that single video once and retries.
101
+ - **Nothing is deleted.** Videos removed upstream stay on disk; the CLI never
102
+ deletes local files.
103
+ - **Filenames:** `<title> [<id8>].mp4` — the id suffix prevents collisions when
104
+ two videos share a title.
105
+ - **Not ready / restricted:** videos that are still processing, or whose
106
+ moderation failed, are skipped and reported.
107
+
108
+ ## Build
109
+
110
+ ```bash
111
+ npm run build # esbuild bundle -> dist/index.js (published artifact)
112
+ ```
113
+
114
+ `prepublishOnly` runs typecheck and build, so a stale `dist/` cannot be
115
+ published.
116
+
117
+ ## Layout
118
+
119
+ ```
120
+ src/index.ts CLI entry and flag parsing
121
+ src/commands/ login, whoami, list, sync, interactive picker
122
+ src/core/client.ts API client (manifest, prepare, whoami)
123
+ src/core/selection.ts folder / collection / search selection
124
+ src/core/sync.ts diffing and orchestration
125
+ src/core/download.ts resumable curl-backed transfer
126
+ src/core/paths.ts folder tree -> local paths
127
+ src/core/state.ts versioned state file
128
+ src/core/events.ts structured progress events (the Tauri seam)
129
+ ```
130
+
131
+ `src/core/` has no CLI-specific code. A Tauri app can bundle the compiled
132
+ binary as a sidecar and render the same events, or the core can be ported
133
+ without touching the orchestration logic.