tars-renderer 1.1.0 → 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

@@ -93,6 +93,15 @@ 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.
@@ -176,4 +185,4 @@ Without `--yes`, any step that would ask (upload, render, delete) stops with exi
 
 ---
 
-**Tars Renderer:** [tars-renderer.vercel.app](https://tars-renderer.vercel.app) (invite-only). Requires Node.js 18+.
+**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,15 +1,19 @@
 {
   "name": "tars-renderer",
-  "version": "1.1.0",
+  "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"
+    "README.md",
+    "LICENSE",
+    "skill/SKILL.md"
   ],
   "engines": {
     "node": ">=18"
@@ -24,7 +28,6 @@
     "video",
     "ai-agent"
   ],
-  "license": "UNLICENSED",
   "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`.

package/tars-renderer.mjs

@@ -12,7 +12,7 @@ import { setMaxListeners } from "node:events";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 
-export const VERSION = "1.1.0";
+export const VERSION = "1.1.1";
 
 /** The Tars Renderer portal. `login` signs in here unless another portal is passed (development, staging). */
 export const DEFAULT_PORTAL = "https://tars-renderer.vercel.app";
@@ -72,7 +72,7 @@ const notLoggedIn = () =>
 
 // ---------------------------------------------------------------- pure helpers (exported for tests)
 
-const BOOLEAN = new Set(["json", "yes", "help", "watch", "mine", "muted", "rehash", "all", "local", "purge"]);
+const BOOLEAN = new Set(["json", "yes", "help", "watch", "mine", "muted", "rehash", "all", "local", "purge", "repo"]);
 const ALIASES = { h: "help", y: "yes" };
 
 /** `--x value`, `--x=value`, boolean `--x`, `-h`/`-y`, `--` ends options. A non-boolean flag without a value is `true`. */
@@ -1625,6 +1625,40 @@ Exit codes: 0 ok, 1 error (read "error" in the JSON), 2 bad usage, 3 confirmatio
 Never print or log the CLI token (kept in the OS credential store, or ~/.tars-renderer/config.json).
 `;
 
+// ---------------------------------------------------------------- agent skill
+
+/** SKILL.md ships inside this package (cli/skill/SKILL.md), so the skill always matches the CLI version. */
+export function readSkill() {
+  return fs.readFileSync(new URL("./skill/SKILL.md", import.meta.url), "utf8");
+}
+
+/** Where each agent looks for skills: user-wide under ~, or per repo under the current folder (--repo). */
+export function skillTargets(forAgent, project, home = os.homedir(), cwd = process.cwd()) {
+  const base = project ? cwd : home;
+  const all = { claude: path.join(base, ".claude", "skills", "tars-renderer"), codex: path.join(base, ".codex", "skills", "tars-renderer") };
+  if (forAgent === "all") return all;
+  if (!(forAgent in all)) throw usage(`--for must be claude, codex or all, got "${forAgent}"`);
+  return { [forAgent]: all[forAgent] };
+}
+
+async function cmdSkill(_, f) {
+  const action = _[0] ?? "show";
+  if (action === "show") return done({ skill: readSkill() }, (d) => process.stdout.write(d.skill));
+  if (action !== "install") throw usage(`Unknown action "${action}". Use: tars-renderer skill install | show`);
+  const targets = skillTargets(typeof f.for === "string" ? f.for : "all", !!f.repo);
+  const skill = readSkill();
+  const installed = Object.entries(targets).map(([agent, dir]) => {
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, "SKILL.md");
+    fs.writeFileSync(file, skill);
+    return { agent, file };
+  });
+  done({ ok: true, installed }, () => {
+    for (const i of installed) say(`${green("✔")} ${i.agent === "claude" ? "Claude Code" : "Codex"}: ${i.file}`);
+    say(dim("  Start a new agent session, then ask it to render your Remotion project."));
+  });
+}
+
 async function cmdAgentGuide(_, f) {
   const cfg = loadConfig();
   const portal = (typeof f.portal === "string" ? f.portal : cfg.portal)?.replace(/\/+$/, "");
@@ -1779,6 +1813,21 @@ hashes every file (SHA-256), shows what changed and asks before uploading. Hashe
     summary: "Delete a project and its uploaded files",
     run: cmdDeleteProject,
   },
+  skill: {
+    args: [],
+    optArgs: ["action"],
+    flags: ["for=", "repo"],
+    usage: "skill [install|show] [--for claude|codex|all] [--repo]",
+    summary: "Add the Tars Renderer skill to Claude Code / Codex",
+    help: `Installs the agent skill, so your coding agent knows how to use Tars Renderer in every session.
+
+  install          write SKILL.md for your agents (default: Claude Code and Codex)
+  show             print the skill (default)
+  --for <agent>    claude, codex or all (default all)
+  --repo           install into this repo (.claude/skills, .codex/skills) instead of your home folder`,
+    examples: ["npx tars-renderer skill install", "tars-renderer skill install --for claude --repo"],
+    run: cmdSkill,
+  },
   "agent-guide": {
     args: [],
     flags: ["portal="],