tars-renderer 0.0.0-stage → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tars (hellotars.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# tars-renderer
 
-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.
+**Render Remotion videos in the cloud from your terminal, or let your AI coding agent do it.**
+
+`tars-renderer` is the command-line client for **Tars Renderer**, the Tars team's Remotion render farm. Upload a built Remotion project, pick a composition, render it on AWS Lambda (hundreds of workers in parallel) and download the MP4, all without AWS keys. Everything you do here also shows up live in the web portal, and the other way round.
+
+- **One command, every OS.** No dependencies; needs Node.js 18 or newer.
+- **Sign in through your browser.** No passwords or keys in the terminal. The token goes into your OS keychain.
+- **Fast transfers.** Only changed files are uploaded, hashes are cached, big files go up in parallel parts, and downloads use 8 parallel connections.
+- **Safe by default.** It shows the cost before every render and asks first. A monthly team budget and per-person limits apply.
+- **Agent-ready.** `--json` output, clear exit codes and a built-in guide for Claude Code, Codex and Cursor.
+
+> **Portal: [tars-renderer.vercel.app](https://tars-renderer.vercel.app).** Access is invite-only. You need a Tars Renderer account (your work email on the allowlist).
+
+---
+
+## Install
+
+```sh
+npm i -g tars-renderer
+tars-renderer --version
+```
+
+Update any time with `npm i -g tars-renderer@latest`.
+
+<details>
+<summary>"tars-renderer" is not recognized / command not found</summary>
+
+- Close and reopen the terminal, so it picks up the new command.
+- Still missing? npm's global folder isn't on your `PATH`. Run `npm prefix -g`; the command lives in that folder (Windows) or its `bin` folder (macOS/Linux). Add it to `PATH`.
+- If npm is blocked on your network, install the copy your portal serves: `npm i -g https://<portal>/cli/tars-renderer.tgz`.
+</details>
+
+## Sign in
+
+```sh
+tars-renderer login
+```
+
+No address needed: the CLI signs in to [tars-renderer.vercel.app](https://tars-renderer.vercel.app).
+
+1. The CLI shows a code such as `KQ7M-4TZP` and opens the portal in your browser.
+2. Sign in if asked, **check that the code matches**, and click **Approve**.
+3. Back in the terminal you're signed in. Check with `tars-renderer doctor`.
+
+Your sign-in lasts 90 days. If an admin removes your access, the CLI stops working immediately.
+
+### Sign out
+
+```sh
+tars-renderer logout            # sign out this device: revoked on the server, removed from your keychain
+tars-renderer logout --all      # sign out every device and agent on your account (lost laptop?)
+tars-renderer logout --purge    # also delete ~/.tars-renderer (settings and upload cache)
+tars-renderer logout --local    # offline: forget the sign-in here only
+```
+
+You can also see your devices, and sign out one or all of them, on the portal's **CLI & Agents** page.
+
+## Quick start
+
+```sh
+# 1. Build your Remotion project (same Remotion version as the renderer, currently 4.0.535)
+npx remotion bundle src/index.ts --out-dir build
+
+# 2. Create a project (once) and upload the build. Only changed files are sent.
+tars-renderer create "Q4 launch film"
+tars-renderer upload build --project q4-launch-film-x7k2
+
+# 3. See the compositions, then render one: it shows the cost and asks first
+tars-renderer comps q4-launch-film-x7k2
+tars-renderer render q4-launch-film-x7k2 Main --res 1080p --watch --download
+```
+
+```
+Main in q4-launch-film-x7k2
+  Output     1920×1080 · 9,360 frames
+  Estimate   $0.94
+  Budget     $12.30 of $50.00 spent this month · 0 active renders of yours
+Start this render for $0.94? [y/N] y
+✔ Render started: k97abc123def456
+▮▮▮▮▮▮▮▮▮▮▮▮▯▯▯▯▯▯▯▯▯▯▯▯  52%  4,867 frames  ~$0.49  1m 12s  rendering
+```
+
+Testing something new? Start small: `--res 360p --seconds 0-10` costs cents.
+
+## Use it with an AI coding agent
+
+Open Claude Code, Codex or Cursor in your Remotion project folder and ask it to render. The agent can run everything itself, and it always shows you the cost and waits for your yes before rendering. Give it the full instructions with:
+
+```sh
+tars-renderer agent-guide
+```
+
+or click **Copy agent instructions** on the portal and paste them into the agent. The agent never needs keys: you approve its sign-in in your own browser, and the CLI only ever shows a masked token (`trp_ab12…`).
+
+### Add the skill to Claude Code or Codex
+
+```sh
+npx -y tars-renderer skill install            # Claude Code and Codex, for all your projects
+npx -y tars-renderer skill install --repo     # only this repo (.claude/skills, .codex/skills)
+```
+
+Once the skill is added, just ask your agent to "render this Remotion project". It knows the whole workflow (version check, build, upload, estimate, render, download), always asks before spending money, and never handles keys. The portal's **CLI & Agents** page can also copy the skill, download it, or give you a prompt that makes the agent save it itself.
+
+## Commands
+
+Every command accepts `--help` and `--json`. `<project>` takes a project slug or id.
+
+| Command | What it does |
+|---|---|
+| `login` | Sign in through the browser (to tars-renderer.vercel.app) |
+| `logout [--all] [--local] [--purge]` | Sign out this device; `--all` signs out every device on your account |
+| `whoami` | Who you're signed in as |
+| `doctor` | Check Node, sign-in, the API connection and your access |
+| `projects [--mine]` | List projects |
+| `create <name> [--keep 7-days\|30-days\|90-days\|never]` | Create a project |
+| `upload <buildDir> --project <project> [--yes]` | Upload a build; only changed files are sent |
+| `comps <project>` | List compositions (size, fps, duration, frames) |
+| `estimate <project> <composition> [render options]` | Cost, output size and frames, without rendering |
+| `render <project> <composition> [render options] [--watch] [--download [path]] [--yes]` | Start a render |
+| `renders [--mine] [--project <p>] [--status <s>]` | List renders |
+| `status <renderId>` | A render's current state |
+| `watch <renderId>` | Follow a render live (exit 0 when done, 1 if it fails) |
+| `download <renderId> [--out <path>]` | Download a finished render |
+| `link <renderId>` | A share link, valid 24 hours |
+| `delete-render <renderId>` / `delete-project <project>` | Delete (asks first) |
+| `agent-guide` | Instructions for AI coding agents |
+
+### Render options
+
+Also accepted by `estimate`.
+
+| Option | Values | Default |
+|---|---|---|
+| `--res` | `360p`, `720p`, `1080p`, `4k` | `1080p` |
+| `--quality` | `draft`, `standard`, `high` | `standard` |
+| `--seconds a-b` | a time range, e.g. `0-10` | whole video |
+| `--frames a-b` | a frame range, inclusive, e.g. `0-299` | whole video |
+| `--muted` | no audio | off |
+| `--keep` | `1-day`, `3-days`, `7-days`, `30-days`, `forever` | `7-days` |
+
+Renders above **$5** always ask for an extra confirmation. Each person can have **2 renders running** at once, and the team has a **monthly budget**.
+
+## How uploads work
+
+- Pass the **build folder** (`index.html` and `bundle.js` at its top). If you pass the project root by mistake, the CLI tells you which folder to use.
+- The Remotion version is read from `bundle.js` and must match the renderer's (use `--version` to override detection).
+- Files are hashed (SHA-256) and only new or changed files are sent. Hashes are cached, so re-uploading an unchanged build takes seconds (`--rehash` ignores the cache).
+- Big files go up in 16 MB parts. Everything shares one parallel queue with retries, and expired upload links are renewed automatically.
+- Builds can have up to 8,000 files, 5 GB per file and 20 GB in total.
+- If an upload fails, run the same command again: anything already uploaded is skipped.
+
+## JSON mode (scripts and agents)
+
+With `--json`, a command prints **exactly one JSON document on stdout**. Progress and logs go to stderr, and errors are JSON too: `{ "ok": false, "error": "…", "exitCode": 1 }`.
+
+| Exit code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Error (see `error`) |
+| `2` | Bad usage |
+| `3` | Confirmation needed. Show the user the details, then re-run with `--yes` |
+| `4` | Not signed in, or the sign-in expired. Run `tars-renderer login` |
+| `130` | Cancelled with Ctrl-C |
+
+Without `--yes`, any step that would ask (upload, render, delete) stops with exit code 3 and prints what it would do, including the cost estimate.
+
+## Security
+
+- Sign-in is a one-time code you approve in your browser, and only allowlisted accounts can approve it.
+- The token is stored in the **macOS Keychain**, **Windows DPAPI** or the **Linux Secret Service**. It's kept in `~/.tars-renderer/config.json` (owner-only) only if none of those is available. `tars-renderer doctor` shows where it is.
+- The CLI masks tokens in all output, only talks to `https://` servers (or localhost for development), and never handles AWS credentials.
+- For CI, set `TARS_RENDERER_API` and `TARS_RENDERER_TOKEN` as environment variables instead of signing in.
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `Not signed in` / exit code 4 | `tars-renderer login` |
+| `This build uses Remotion X` | Pin `remotion` and every `@remotion/*` package to the renderer's version, rebuild, upload again |
+| `index.html and bundle.js not found` | Pass the `build` folder, not the project root |
+| `A render of this project is running` | Wait for it to finish, then re-upload |
+| `access denied` when approving | Ask an admin to add your work email |
+| Anything else | `tars-renderer doctor`, then `DEBUG=1 tars-renderer <command>` for details |
+
+---
+
+**Tars Renderer:** [tars-renderer.vercel.app](https://tars-renderer.vercel.app) (invite-only). Requires Node.js 18+. Licensed under the [MIT License](./LICENSE).

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "tars-renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "description": "Command line for the Tars Renderer: upload Remotion builds, render on AWS Lambda, download the MP4.",
+  "homepage": "https://tars-renderer.vercel.app",
+  "author": "Tars (https://hellotars.com)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "tars-renderer": "tars-renderer.mjs"
+  },
+  "files": [
+    "tars-renderer.mjs",
+    "README.md",
+    "LICENSE",
+    "skill/SKILL.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "remotion",
+    "render",
+    "lambda",
+    "cli",
+    "tars",
+    "remotion-lambda",
+    "video",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: tars-renderer
+description: Render Remotion videos in the cloud with Tars Renderer (the team's AWS Lambda render farm) through the `tars-renderer` CLI. Use when the user wants to render or export a Remotion composition to MP4, upload a Remotion build, check cost or render progress, list or download renders, or sign in to Tars Renderer from the terminal.
+---
+
+# Tars Renderer
+
+Tars Renderer renders Remotion projects on AWS Lambda for the Tars team: upload a built project, pick a composition, get an MP4 back. You drive it with the `tars-renderer` CLI. The portal is https://tars-renderer.vercel.app. The user never needs AWS keys.
+
+## Ground rules
+
+- **Never ask for or handle secrets.** Sign-in happens in the user's browser. Don't open, read, print or copy anything in `~/.tars-renderer/`. The CLI only ever shows a masked token (`trp_ab12…`); if you see a full one, stop and tell the user to sign that device out on the portal's CLI & Agents page.
+- **Cost needs a yes.** Always run `estimate` first, tell the user the cost, output size and frames, and only start the render (with `--yes`) after they agree.
+- **Test small first.** For a first or experimental render, suggest `--res 360p --seconds 0-5`.
+- **Don't change the user's code**, except pinning Remotion versions (step 2), and only after they agree.
+- **Read results with `--json`.** One JSON document goes to stdout; progress and logs go to stderr.
+- **On failure, stop and explain** what happened and what you suggest. Don't loop on retries.
+
+## Workflow
+
+### 1. Make sure the CLI is ready
+
+```sh
+tars-renderer doctor --json
+```
+
+- `command not found`: install it with `npm i -g tars-renderer` (Node.js 18+), or prefix commands with `npx -y tars-renderer`.
+- Exit code **4** (not signed in): ask the user to run `tars-renderer login` themselves. A browser tab opens; they check that the code matches and click Approve. Wait for them, then run `doctor` again.
+- Access denied: the user's work email isn't on the allowlist; they can request access on the portal.
+
+### 2. Check the Remotion version
+
+The renderer supports Remotion **4.0.535** exactly. In the project folder run `npx remotion versions`. If anything differs:
+
+1. Detect the package manager from the lockfile (npm, pnpm, yarn or bun).
+2. Propose pinning `remotion` and every `@remotion/*` package to exactly 4.0.535 (npm: `npm i --save-exact remotion@4.0.535 @remotion/cli@4.0.535 …`; pnpm: `pnpm add --save-exact`; yarn: `yarn add --exact`; bun: `bun add --exact`).
+3. Run it only after the user agrees, then check again.
+
+### 3. Build
+
+Find the entry file that calls `registerRoot` (usually `src/index.ts`, `src/index.tsx` or `remotion/index.ts`), then:
+
+```sh
+npx remotion bundle src/index.ts --out-dir build
+```
+
+The `build` folder must contain `index.html` and `bundle.js`.
+
+### 4. Pick or create the project
+
+```sh
+tars-renderer projects --mine --json
+```
+
+Reuse a project for this repo if one exists (match by name). Otherwise ask the user for a name, then:
+
+```sh
+tars-renderer create "<name>" --json      # returns the project slug
+```
+
+### 5. Upload
+
+```sh
+tars-renderer upload build --project <slug> --yes --json
+```
+
+Only changed files are sent, so re-uploading is fast. The JSON lists the compositions found. Uploads are refused while a render of that project is running; wait for it to finish.
+
+### 6. Choose and estimate
+
+```sh
+tars-renderer comps <slug> --json
+tars-renderer estimate <slug> <composition> --res 1080p --json
+```
+
+Ask the user which composition and settings to use if they didn't say. Options: `--res 360p|720p|1080p|4k`, `--quality draft|standard|high`, `--seconds a-b` or `--frames a-b`, `--muted`, `--keep 1-day|3-days|7-days|30-days|forever`. Report `estimateUsd`, the output size and the frames, and any `blockedReason` (monthly budget, per-person cap, or too many renders running).
+
+### 7. Render, then download
+
+After the user agrees to the cost:
+
+```sh
+tars-renderer render <slug> <composition> [same options] --yes --watch --json
+tars-renderer download <renderId> --out <file>.mp4 --json
+```
+
+`--watch` follows progress until the render is done (exit 0) or fails (exit 1). Tell the user where the file was saved. They can also watch it on the portal's Renders page.
+
+## Exit codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | OK | Continue |
+| 1 | Error | Read `error` in the JSON, explain it, stop |
+| 2 | Bad usage | Fix the command (check `tars-renderer <command> --help`) |
+| 3 | Confirmation needed | Show the user the details, re-run with `--yes` only if they agree |
+| 4 | Not signed in | Ask the user to run `tars-renderer login` |
+
+## Common problems
+
+| Message | Fix |
+|---|---|
+| `This build uses Remotion X` | Pin to 4.0.535 (step 2), rebuild, upload again |
+| `index.html and bundle.js not found` | Pass the `build` folder, not the project root |
+| `A render of this project is running` | Wait for it, then upload |
+| Over budget / too many renders | Tell the user; an admin can raise limits on the portal's Usage & limits page |
+| Render failed | Show the error from `tars-renderer status <id> --json`; try 360p with a short range |
+
+## Other useful commands
+
+`tars-renderer renders --mine --json` (recent renders), `tars-renderer status <id> --json`, `tars-renderer link <id>` (24-hour share link), `tars-renderer logout` (`--all` signs out every device), `tars-renderer --help`.