Skip to content

Text to motion graphics for Claude Code and Codex: write a brief, get a checked MP4. 30 art forms from claymation and paper cut-out to anime and pixel art, 2D explainers, Shorts, 3D products. Installs brief2motion for websites. MIT.

fix: installers never adopt or delete user folders; Windows gpg path; PS 5.1 in CI; audit LOWs

Varun Pratap Bhardwaj9a24dd7c50fd
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 51f398e..ab23758 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -78,5 +78,20 @@ jobs:
bash plugin/skills/brief2mp4/scripts/finish.sh --in .tmp/out/cut.mp4 --out .tmp/out/final.mp4 --seconds 5 --size 1280x720 --audio .tmp/out/mix.wav
bash plugin/skills/brief2mp4/scripts/check_delivery.sh .tmp/out/final.mp4 --seconds 5 --size 1280x720
+ - name: Windows PowerShell 5.1 (the version that ships with Windows)
+ if: runner.os == 'Windows'
+ shell: powershell
+ run: |
+ $PSVersionTable.PSVersion.ToString()
+ $env:CLAUDE_CONFIG_DIR = "$env:RUNNER_TEMP\ps51-claude"
+ .\install.ps1 -Claude
+ if (-not (Test-Path "$env:CLAUDE_CONFIG_DIR\skills\brief2mp4\SKILL.md")) { throw "install.ps1 did not install the skill under PowerShell 5.1" }
+ .\install.ps1 -Claude -Uninstall
+ .\plugin\skills\brief2mp4\edit\install_edit.ps1 -Components film,sound -DryRun
+ $d3 = .\plugin\skills\brief2mp4\scripts\detect_3d.ps1; $d3
+ if ($d3 -notlike "3d: ready*") { throw "detect_3d.ps1 under PowerShell 5.1: $d3" }
+ $de = .\plugin\skills\brief2mp4\scripts\detect_edit.ps1; $de
+ if ($de -notlike "edit: ready*") { throw "detect_edit.ps1 under PowerShell 5.1: $de" }
+
- name: Fast tests
run: bash tests/run_tests.sh -rs
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2a8666f..3fa3d7b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,7 +6,7 @@ All notable changes to brief2mp4. The format follows [Keep a Changelog](https://
### Added
- **Optional 3D pack** (`plugin/skills/brief2mp4/3d/`): CAD and mesh models to GLB, material presets, deterministic Jolt physics bakes, shot JSON to a frame-seekable HyperFrames project, and a Blender hero-render route. Installs per component (`core`, `cad`, `blender`) with `install.sh --with-3d` or `install.ps1 -With3D`. The skill detects it and falls back to the Three.js template when it is missing.
-- **Optional edit pack** (`plugin/skills/brief2mp4/edit/`): installs the command-line tools of five free ArtCraft editors by storytold (FilmCraft, SoundCraft, EffectCraft, PhotoCraft, VectorCraft; Apache-2.0) at pinned versions, on macOS, Windows and Linux. Each download must match both the release's SHA256SUMS.txt and the hash pinned in this repository, and the release signature is verified against a pinned key fingerprint when gpg is present. One tested recipe per app: a timeline cut with a dissolve and title, a voice-over mix with ducking, an animated title, a thumbnail and an SVG lower third. `install.sh --with-edit`, `install.ps1 -WithEdit`, `scripts/detect_edit.sh`, example 07.
+- **Optional edit pack** (`plugin/skills/brief2mp4/edit/`): installs the command-line tools of five free ArtCraft editors by storytold (FilmCraft, SoundCraft, EffectCraft, PhotoCraft, VectorCraft; MIT or Apache-2.0) at pinned versions, on macOS, Windows and Linux. Each download must match both the release's SHA256SUMS.txt and the hash pinned in this repository, and the release signature is verified against a pinned key fingerprint when gpg is present. One tested recipe per app: a timeline cut with a dissolve and title, a voice-over mix with ducking, an animated title, a thumbnail and an SVG lower third. `install.sh --with-edit`, `install.ps1 -WithEdit`, `scripts/detect_edit.sh`, example 07.
- **SETUP.md**: step-by-step instructions an agent follows to set up a machine on macOS, Windows or Linux, ending with a two-minute first render.
- **Windows support**: `install.ps1` (PowerShell 5.1 and 7, optional winget install of Node, ffmpeg and Git), Git Bash guidance in the skill.
- `scripts/doctor.sh` (with `--json`): checks every tool and prints the install command for this OS. `scripts/detect_3d.sh`. `scripts/bounds.py`: measures where content sits in a still and checks margins and safe zones, standard library only. `scripts/vendor_libs.sh`: pinned GSAP, three.js and fonts copied into a project. `sound_bed.sh --ticks` for click accents.
@@ -16,7 +16,7 @@ All notable changes to brief2mp4. The format follows [Keep a Changelog](https://
- `references/ecosystem.md`: 45+ open-source motion, 3D, capture and agent-skill repos with licences, when each beats the default, and how to bring its output in frame-exact.
- Example 04: a 3D product brief (parts drop and settle, exploded view, title).
- `docs/`: getting started (per OS, with a flow diagram), architecture (the loop, routing, determinism, the 3D pack) and a 3D walkthrough of example 04.
-- Tests (`tests/`, 46 including render tests) and CI on macOS, Ubuntu and Windows.
+- Tests (`tests/`, 97: 76 fast, 21 that render or download, run with `--slow`) and CI on macOS, Ubuntu and Windows, including Windows PowerShell 5.1.
- `AGENTS.md` and `CLAUDE.md` so an agent opened in a clone knows what to do; CONTRIBUTING, SECURITY, code of conduct, issue and PR templates.
### Fixed (from an independent pre-release audit)
diff --git a/README.md b/README.md
index 58d541b..bcee6cb 100644
--- a/README.md
+++ b/README.md
@@ -164,7 +164,7 @@ The brief does the asking. "Parts fall and settle" becomes a physics bake with a
## The edit pack
-Motion graphics are half of a video. The other half is editing: cutting your screen recording or footage on a timeline, mixing a voiceover over music so the music ducks when you speak, compositing titles, making the thumbnail. The optional edit pack installs the command-line tools of five free, open-source desktop editors, the ArtCraft apps by [storytold](https://github.com/storytold) (Apache-2.0), so Claude Code or Codex can do that work too, headless, and hand the result to the same checks.
+Motion graphics are half of a video. The other half is editing: cutting your screen recording or footage on a timeline, mixing a voiceover over music so the music ducks when you speak, compositing titles, making the thumbnail. The optional edit pack installs the command-line tools of five free, open-source desktop editors, the ArtCraft apps by [storytold](https://github.com/storytold) (MIT or Apache-2.0, at your option), so Claude Code or Codex can do that work too, headless, and hand the result to the same checks.
<p align="center">
<img src="assets/edit-pack-recipes.png" alt="Output of the four edit-pack recipes: a FilmCraft timeline mid cross-dissolve, an EffectCraft animated title, a PhotoCraft thumbnail reading Cut faster, and a VectorCraft lower third" width="720">
@@ -264,12 +264,13 @@ plugin/
skills/brief2mp4/
SKILL.md the loop the agent follows
references/ formats, pipelines, ecosystem, hyperframes, threejs, blender, ffmpeg
- scripts/ finish, check_delivery, contact_sheet, sound_bed, doctor, detect_3d
+ scripts/ finish, check_delivery, contact_sheet, sound_bed, doctor, detect_3d,
+ detect_edit, bounds.py, vendor_libs
templates/ SPEC.md, a Three.js scene, a Blender turntable
3d/ the optional 3D pack and its installers
edit/ the optional edit pack: verified installers, pinned versions, recipes
docs/ getting started, architecture, 3D walkthrough
-examples/ six briefs; 01, 04, 05 and 06 with sample reports or a worked build
+examples/ seven briefs; 01, 05, 06 and 07 with sample reports, 04 with a worked build
tests/ fast checks and render tests (bash tests/run_tests.sh [--slow])
```
@@ -279,6 +280,6 @@ Bad results are the most useful bug reports: open a **Brief result** issue with
## Licence
-MIT. Use it, change it, ship videos with it. HyperFrames (Apache-2.0), Three.js (MIT), GSAP (standard no-charge licence), Jolt (MIT), glTF-Transform (MIT), meshoptimizer (MIT), Manifold (Apache-2.0), CadQuery (Apache-2.0), trimesh (MIT), Blender (GPL), ffmpeg (LGPL/GPL) and the ArtCraft apps by storytold (Apache-2.0, downloaded from their own releases by the edit pack) keep their own licences; this repo does not bundle them.
+MIT. Use it, change it, ship videos with it. HyperFrames (Apache-2.0), Three.js (MIT), GSAP (standard no-charge licence), Jolt (MIT), glTF-Transform (MIT), meshoptimizer (MIT), Manifold (Apache-2.0), CadQuery (Apache-2.0), trimesh (MIT), Blender (GPL), ffmpeg (LGPL/GPL) and the ArtCraft apps by storytold (MIT or Apache-2.0, downloaded from their own releases by the edit pack) keep their own licences; this repo does not bundle them.
Made by [Varun Pratap Bhardwaj](https://github.com/qualixar).
diff --git a/SETUP.md b/SETUP.md
index bcd15d3..59633b2 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -72,7 +72,7 @@ powershell -ExecutionPolicy Bypass -File .\install.ps1 -With3D core,cad
Install the 3D pack only when the user wants 3D products, physics, exploded views or turntables. Everything else works without it. The pack is described in `plugin/skills/brief2mp4/3d/README-3D.md`.
-Install the edit pack when the user edits real footage or recordings, mixes voice-over with music, or wants thumbnails and lower thirds made by the agent: `bash install.sh --with-edit` (FilmCraft and SoundCraft; `--with-edit=film,sound,effect,photo,vector` for all five) or `install.ps1 -WithEdit film,sound`. It downloads the free ArtCraft editors' command-line tools from their GitHub releases and checks each file's SHA-256 and signature before unpacking. Details: `plugin/skills/brief2mp4/edit/README-EDIT.md`.
+Install the edit pack when the user edits real footage or recordings, mixes voice-over with music, or wants thumbnails and lower thirds made by the agent: `bash install.sh --with-edit` (FilmCraft and SoundCraft; `--with-edit=film,sound,effect,photo,vector` for all five) or `install.ps1 -WithEdit film,sound`. It downloads the free ArtCraft editors' command-line tools from their GitHub releases and checks each file's SHA-256 (against the release and against a hash pinned in this repository) before unpacking; when gpg is installed it also verifies the release signature. Details: `plugin/skills/brief2mp4/edit/README-EDIT.md`.
The user may prefer the plugin route instead of the script. Then they run, inside Claude Code: `/plugin marketplace add qualixar/brief2mp4` and `/plugin install brief2mp4@brief2mp4`; in a terminal for Codex: `codex plugin marketplace add qualixar/brief2mp4` and `codex plugin add brief2mp4@brief2mp4`. Plugins do not install system tools, so Step 2 still applies.
diff --git a/docs/3d-walkthrough.md b/docs/3d-walkthrough.md
index 094d6ac..f3bfed8 100644
--- a/docs/3d-walkthrough.md
+++ b/docs/3d-walkthrough.md
@@ -63,7 +63,8 @@ npx --yes [email protected] render . -o ../render.mp4 --quality delivery --fps
Each `b2m3d` subcommand prints one JSON result (`build.py` hides them for brevity; run the steps by hand to see them), so an agent can read exactly what happened. Then finish and check:
```bash
-S=plugin/skills/brief2mp4/scripts
+cd .. # back to ~/videos/ex04, where render.mp4 is
+S=/path/to/brief2mp4/plugin/skills/brief2mp4/scripts # your clone, or the installed skill folder
bash $S/sound_bed.sh bed.wav --seconds 8 --hits 0.6,1.2,1.8,2.4,3.0,3.2
bash $S/finish.sh --in render.mp4 --out final.mp4 --seconds 8 --audio bed.wav
bash $S/check_delivery.sh final.mp4 --seconds 8 --size 1920x1080 --fps 30
diff --git a/plugin/skills/brief2mp4/3d/README-3D.md b/plugin/skills/brief2mp4/3d/README-3D.md
index f6ed0f4..9c2941b 100644
--- a/plugin/skills/brief2mp4/3d/README-3D.md
+++ b/plugin/skills/brief2mp4/3d/README-3D.md
@@ -33,7 +33,7 @@ powershell -ExecutionPolicy Bypass -File 3d\install_3d.ps1 -Components core
powershell -ExecutionPolicy Bypass -File 3d\install_3d.ps1 -Components core,cad
```
-Run these from this skill's folder (or give the full path). The installer needs Node.js 20 or newer and Python 3.12 or 3.13 on the PATH (the pinned numpy and scipy need 3.12+). If one is missing it stops and prints the command that installs it. To use a specific interpreter (for example one from uv on Debian 12, which ships 3.11), set `B2M3D_PYTHON`: `B2M3D_PYTHON="$(uv python find 3.12)" bash 3d/install_3d.sh`. Remove the pack with `bash 3d/install_3d.sh --uninstall` (or `install_3d.ps1 -Uninstall`); it only deletes a folder it created. It installs into `~/.brief2mp4/3d` (Windows: `%USERPROFILE%\.brief2mp4\3d`), keeps a Python venv, a `node_modules` folder and its own copy of the pack there (so moving or deleting the clone or plugin cache does not break it), prints what it installs and the disk size, and is safe to run again: finished work is skipped. Set `B2M3D_HOME` to use another folder. Versions are pinned in `requirements-core.txt`, `requirements-cad.txt` and `package.json` (with `package-lock.json`).
+Run these from this skill's folder (or give the full path). The installer needs Node.js 22 or newer and Python 3.12 or 3.13 on the PATH (the pinned numpy and scipy need 3.12+). If one is missing it stops and prints the command that installs it. To use a specific interpreter (for example one from uv on Debian 12, which ships 3.11), set `B2M3D_PYTHON`: `B2M3D_PYTHON="$(uv python find 3.12)" bash 3d/install_3d.sh`. Remove the pack with `bash 3d/install_3d.sh --uninstall` (or `install_3d.ps1 -Uninstall`); it only deletes a folder it created. It installs into `~/.brief2mp4/3d` (Windows: `%USERPROFILE%\.brief2mp4\3d`), keeps a Python venv, a `node_modules` folder and its own copy of the pack there (so moving or deleting the clone or plugin cache does not break it), prints what it installs and the disk size, and is safe to run again: finished work is skipped. Set `B2M3D_HOME` to use another folder. Versions are pinned in `requirements-core.txt`, `requirements-cad.txt` and `package.json` (with `package-lock.json`).
After install the command is `~/.brief2mp4/3d/venv/bin/brief2mp4-3d` (Windows: `venv\Scripts\brief2mp4-3d.cmd`), or `~/.brief2mp4/3d/venv/bin/python -m b2m3d` from any folder. The examples below write `b2m3d` for either form.
diff --git a/plugin/skills/brief2mp4/3d/b2m3d/doctor.py b/plugin/skills/brief2mp4/3d/b2m3d/doctor.py
index 9bcce5a..20a1e50 100644
--- a/plugin/skills/brief2mp4/3d/b2m3d/doctor.py
+++ b/plugin/skills/brief2mp4/3d/b2m3d/doctor.py
@@ -56,7 +56,7 @@ def check_core() -> dict:
node = paths.node()
node_pkgs = _node_versions()
py_mods = _py_modules(CORE_PY_MODULES)
- missing = (([] if node else ["node on PATH (Node.js 20 or newer)"])
+ missing = (([] if node else ["node on PATH (Node.js 22 or newer)"])
+ [f"npm:{k}" for k, v in node_pkgs.items() if v is None]
+ [f"python:{k}" for k, v in py_mods.items() if not v])
return {"ok": not missing, "missing": missing, "node": node, "node_packages": node_pkgs,
diff --git a/plugin/skills/brief2mp4/3d/b2m3d/run.py b/plugin/skills/brief2mp4/3d/b2m3d/run.py
index 269314a..bb87df8 100644
--- a/plugin/skills/brief2mp4/3d/b2m3d/run.py
+++ b/plugin/skills/brief2mp4/3d/b2m3d/run.py
@@ -47,7 +47,7 @@ def sync_js() -> Path:
def node_script(script: str, args: list[str], timeout: int = 3600) -> str:
node = paths.node()
if not node:
- raise B2M3DError("node was not found on PATH (Node.js 20 or newer is required)")
+ raise B2M3DError("node was not found on PATH (Node.js 22 or newer is required)")
return run([node, str(sync_js() / script), *args], timeout=timeout)
diff --git a/plugin/skills/brief2mp4/3d/install_3d.ps1 b/plugin/skills/brief2mp4/3d/install_3d.ps1
index 041c669..b9c7b14 100644
--- a/plugin/skills/brief2mp4/3d/install_3d.ps1
+++ b/plugin/skills/brief2mp4/3d/install_3d.ps1
@@ -22,12 +22,21 @@ $Venv = Join-Path $HomeDir "venv"
$VPy = Join-Path $Venv "Scripts\python.exe"
$Marker = Join-Path $HomeDir ".installed-by-brief2mp4-3d"
+# Only these entries are ever created in $HomeDir. Uninstall removes exactly these, then the folder
+# itself only if nothing else is left in it.
+$Owned = @("venv", "node_modules", "pack", "js", "package.json", "package-lock.json", ".node-stamp", ".components", ".installed-by-brief2mp4-3d")
if ($Uninstall) {
- if (Test-Path $Marker) { Remove-Item -LiteralPath $HomeDir -Recurse -Force; Write-Output "removed $HomeDir" }
- elseif (Test-Path $HomeDir) { throw "$HomeDir was not created by this script; left it alone" }
- else { Write-Output "nothing to remove at $HomeDir" }
+ if (-not (Test-Path $HomeDir)) { Write-Output "nothing to remove at $HomeDir"; exit 0 }
+ if (-not (Test-Path $Marker)) { throw "$HomeDir was not created by this script; left it alone" }
+ foreach ($e in $Owned) { $p = Join-Path $HomeDir $e; if (Test-Path -LiteralPath $p) { Remove-Item -LiteralPath $p -Recurse -Force } }
+ if (@(Get-ChildItem -LiteralPath $HomeDir -Force).Count -eq 0) { Remove-Item -LiteralPath $HomeDir -Force; Write-Output "removed $HomeDir" }
+ else { Write-Output "removed the 3D pack from $HomeDir; other files in it were left alone" }
exit 0
}
+# Never adopt a folder that already holds someone else's files: the marker would let uninstall touch it.
+if ((Test-Path $HomeDir) -and -not (Test-Path $Marker) -and (@(Get-ChildItem -LiteralPath $HomeDir -Force).Count -gt 0)) {
+ throw "$HomeDir already exists and was not created by this installer. Set B2M3D_HOME to a new or empty folder."
+}
# Accept "-Components core,cad" (an array), "core cad" or "core,cad" (one string) alike.
$wanted = @($Components | ForEach-Object { $_ -split "[,\s]+" } | ForEach-Object { $_.Trim() } | Where-Object { $_ })
if ($wanted.Count -eq 0) { throw "-Components needs a value, e.g. core,cad" }
@@ -108,10 +117,10 @@ function Link-Pack {
}
function Install-Core {
- if (-not (Get-Command node -ErrorAction SilentlyContinue)) { throw "node not found. Install Node.js 20 or newer: winget install OpenJS.NodeJS.LTS" }
+ if (-not (Get-Command node -ErrorAction SilentlyContinue)) { throw "node not found. Install Node.js 22 or newer: winget install OpenJS.NodeJS.LTS" }
if (-not (Get-Command npm.cmd -ErrorAction SilentlyContinue)) { throw "npm not found. It ships with Node.js: https://nodejs.org" }
$major = [int](node -p "process.versions.node.split('.')[0]")
- if ($major -lt 20) { throw "Node.js $major is too old: 20 or newer is needed." }
+ if ($major -lt 22) { throw "Node.js $major is too old: 22 or newer is needed." }
$py = Find-Python
if (-not $py) { throw "Python 3.12 or 3.13 not found. Install it: winget install Python.Python.3.13 (then open a new terminal)." }
diff --git a/plugin/skills/brief2mp4/3d/install_3d.sh b/plugin/skills/brief2mp4/3d/install_3d.sh
index 2ac2d50..6f51421 100755
--- a/plugin/skills/brief2mp4/3d/install_3d.sh
+++ b/plugin/skills/brief2mp4/3d/install_3d.sh
@@ -33,13 +33,25 @@ while [[ $# -gt 0 ]]; do
esac
done
+# Only these entries are ever created in $HOME_DIR. Uninstall removes exactly these, then the folder
+# itself only if nothing else is left in it, so a folder you also use for other things keeps them.
+OWNED="venv node_modules pack js package.json package-lock.json .node-stamp .components .components.tmp $MARKER"
+
if [[ "$UNINSTALL" == 1 ]]; then
- if [[ -f "$HOME_DIR/$MARKER" ]]; then rm -r "$HOME_DIR"; echo "removed $HOME_DIR"
- elif [[ -e "$HOME_DIR" ]]; then echo "install_3d.sh: $HOME_DIR was not created by this script; left it alone" >&2; exit 1
- else echo "nothing to remove at $HOME_DIR"; fi
+ if [[ ! -e "$HOME_DIR" ]]; then echo "nothing to remove at $HOME_DIR"; exit 0; fi
+ [[ -f "$HOME_DIR/$MARKER" ]] || { echo "install_3d.sh: $HOME_DIR was not created by this script; left it alone" >&2; exit 1; }
+ for e in $OWNED; do [[ -e "$HOME_DIR/$e" ]] && rm -rf "${HOME_DIR:?}/$e"; done
+ if rmdir "$HOME_DIR" 2>/dev/null; then echo "removed $HOME_DIR"
+ else echo "removed the 3D pack from $HOME_DIR; other files in it were left alone"; fi
exit 0
fi
+# Never adopt a folder that already holds someone else's files: the marker would let uninstall touch it.
+if [[ -d "$HOME_DIR" && ! -f "$HOME_DIR/$MARKER" && -n "$(ls -A "$HOME_DIR" 2>/dev/null)" ]]; then
+ echo "install_3d.sh: $HOME_DIR already exists and was not created by this installer. Set B2M3D_HOME to a new or empty folder." >&2
+ exit 1
+fi
+
want() { [[ ",$COMPONENTS," == *",$1,"* ]]; }
for c in ${COMPONENTS//,/ }; do
case "$c" in core|cad|blender|dev) ;; *) echo "install_3d.sh: unknown component '$c' (core, cad, blender, dev)" >&2; exit 2 ;; esac
@@ -68,10 +80,10 @@ find_python() {
}
install_core() {
- command -v node >/dev/null 2>&1 || { say "node not found. Install Node.js 20 or newer (macOS: brew install node; Linux: your package manager or https://nodejs.org)." >&2; exit 1; }
+ command -v node >/dev/null 2>&1 || { say "node not found. Install Node.js 22 or newer (macOS: brew install node; Linux: your package manager or https://nodejs.org)." >&2; exit 1; }
command -v npm >/dev/null 2>&1 || { say "npm not found. It ships with Node.js: https://nodejs.org" >&2; exit 1; }
local major; major="$(node -p 'process.versions.node.split(".")[0]')"
- [[ "$major" -ge 20 ]] || { say "Node.js $major is too old: 20 or newer is needed." >&2; exit 1; }
+ [[ "$major" -ge 22 ]] || { say "Node.js $major is too old: 22 or newer is needed." >&2; exit 1; }
local py
py="$(find_python)" || { say "Python 3.12 or 3.13 not found. macOS: brew install [email protected]. Debian/Ubuntu: python3.13 and python3.13-venv from your package manager. Then run this again." >&2; exit 1; }
diff --git a/plugin/skills/brief2mp4/SKILL.md b/plugin/skills/brief2mp4/SKILL.md
index 54e4c1b..3d30370 100644
--- a/plugin/skills/brief2mp4/SKILL.md
+++ b/plugin/skills/brief2mp4/SKILL.md
@@ -79,7 +79,7 @@ Run `bash <this skill's folder>/scripts/detect_edit.sh`. If it prints `edit: rea
Edited output is a layer or a soundtrack like any other: a FilmCraft cut or an EffectCraft render goes into HyperFrames as video, a SoundCraft bounce goes to `finish.sh --audio`, and every route still ends with `finish.sh`, `check_delivery.sh` and the stills you look at.
-If it prints `edit: not installed`, cut with ffmpeg (`references/ffmpeg.md`) and mix with ffmpeg filters, and mention once how to add the pack: `bash <this skill's folder>/edit/install_edit.sh --components film,sound` (Windows: `install_edit.ps1 -Components film,sound`).
+If it prints `edit: not installed`, cut with ffmpeg (`references/ffmpeg.md`) and mix with ffmpeg filters, and mention once how to add the pack: `bash <this skill's folder>/edit/install_edit.sh --components film,sound` (Windows: `powershell -ExecutionPolicy Bypass -File <this skill's folder>\edit\install_edit.ps1 -Components film,sound`).
For briefs that mix tools, read `references/pipelines.md` (architecture, recipes for each mix, how layers meet in HyperFrames). For tools outside this stack (Remotion, Motion Canvas, Manim, Lottie, Rive, PixiJS, R3F, Babylon.js and more), read `references/ecosystem.md`: when each one beats the default, and how to bring its output in frame-exact.
diff --git a/plugin/skills/brief2mp4/edit/README-EDIT.md b/plugin/skills/brief2mp4/edit/README-EDIT.md
index 9e776bd..be2ed14 100644
--- a/plugin/skills/brief2mp4/edit/README-EDIT.md
+++ b/plugin/skills/brief2mp4/edit/README-EDIT.md
@@ -2,7 +2,7 @@
brief2mp4 works without this folder. The pack adds real editing tools for briefs that are more than "generate a graphic and finish it with ffmpeg": footage cut on a timeline, a multitrack audio mix, layered compositing, image editing, vector art. It installs the command-line tools of five free desktop apps, pinned to exact versions, and ships one tested recipe per app.
-The apps are the ArtCraft family by **storytold**, released under **Apache-2.0** (each download carries its own `LICENSE-APACHE` and `NOTICE` files; read them). brief2mp4 does not redistribute them: the installer downloads each release from `github.com/storytold`. **They are alpha software.** Command ids and parameters change between versions, which is why this pack pins versions, tests its recipes against the pinned ones, and tells agents to discover commands at run time.
+The apps are the ArtCraft family by **storytold**, released under **MIT or Apache-2.0** (each app is licensed MIT or Apache-2.0 at your option, per its `NOTICE`; each download carries `LICENSE-MIT`, `LICENSE-APACHE`, `NOTICE` and font licences; read them). brief2mp4 does not redistribute them: the installer downloads each release from `github.com/storytold`. **They are alpha software.** Command ids and parameters change between versions, which is why this pack pins versions, tests its recipes against the pinned ones, and tells agents to discover commands at run time.
| Component | App | Pinned | What it is |
|---|---|---|---|
@@ -51,7 +51,7 @@ Everything goes into `~/.brief2mp4/edit` (Windows `%USERPROFILE%\.brief2mp4\edit
| download: vector | 127.8 MB | 150.4 MB | 155.4 MB |
| download: all five | 420.4 MB | 489.3 MB | 500.2 MB |
-Measured on macOS after install: filmcraft 179 MB, soundcraft 22 MB, effectcraft 187 MB, photocraft 222 MB, vectorcraft 253 MB, about 1.2 GB for all five. Linux and Windows disk sizes were not measured. The Linux and Windows archives hold the whole desktop app next to the CLI (inspected for SoundCraft), and the installer keeps that folder as it came.
+Measured on macOS after install: filmcraft 179 MB, soundcraft 22 MB, effectcraft 187 MB, photocraft 236 MB, vectorcraft 254 MB, about 880 MB for all five. Linux and Windows disk sizes were not measured. The Linux and Windows archives hold the whole desktop app next to the CLI (inspected for SoundCraft), and the installer keeps that folder as it came.
To put the launchers on your PATH the installer prints one line to run yourself. The recipes do not need that: they find the pinned CLIs through `B2M_EDIT_HOME` and never use an older copy that happens to be on the PATH.
diff --git a/plugin/skills/brief2mp4/edit/install_edit.ps1 b/plugin/skills/brief2mp4/edit/install_edit.ps1
index ff7e216..9b037cb 100644
--- a/plugin/skills/brief2mp4/edit/install_edit.ps1
+++ b/plugin/skills/brief2mp4/edit/install_edit.ps1
@@ -71,11 +71,11 @@ function Invoke-Native([string]$file, [string[]]$arguments, [hashtable]$environm
$psi.RedirectStandardError = $true
$psi.CreateNoWindow = $true
foreach ($k in $environment.Keys) { $psi.EnvironmentVariables[$k] = $environment[$k] }
- try { $p = [System.Diagnostics.Process]::Start($psi) } catch { return [pscustomobject]@{ ExitCode = -1; Output = "" } }
+ try { $p = [System.Diagnostics.Process]::Start($psi) } catch { return [pscustomobject]@{ ExitCode = -1; Output = ""; Error = $_.Exception.Message } }
+ $errTask = $p.StandardError.ReadToEndAsync() # read both pipes at once, so neither can fill up and block
$out = $p.StandardOutput.ReadToEnd()
- $null = $p.StandardError.ReadToEnd()
$p.WaitForExit()
- return [pscustomobject]@{ ExitCode = $p.ExitCode; Output = $out }
+ return [pscustomobject]@{ ExitCode = $p.ExitCode; Output = $out; Error = $errTask.Result }
}
function Add-ToManifest([string]$rel) {
@@ -84,6 +84,21 @@ function Add-ToManifest([string]$rel) {
if ($lines -notcontains $rel) { [System.IO.File]::WriteAllLines($Manifest, @($lines + $rel), $Utf8) }
}
+function Test-InManifest([string]$rel) {
+ if (-not (Test-Path $Manifest)) { return $false }
+ return @([System.IO.File]::ReadAllLines($Manifest, $Utf8)) -contains $rel
+}
+
+function Set-Claim([string]$rel) {
+ # Before writing a path, move aside anything there that this installer did not create.
+ $p = Join-Path $HomeDir $rel
+ if ((Test-Path -LiteralPath $p) -and -not (Test-InManifest $rel)) {
+ $aside = "$p.backup-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+ Move-Item -LiteralPath $p -Destination $aside
+ Write-Output " kept your existing $rel at $aside (it was not created by this installer)"
+ }
+}
+
function Test-Hash([string]$file, [string]$asset, [string]$sums, [string]$pinned) {
$line = [System.IO.File]::ReadAllLines($sums, $Utf8) | Where-Object { ($_ -split "\s+")[1] -eq $asset } | Select-Object -First 1
if (-not $line) { throw "$asset is not listed in the release's SHA256SUMS.txt" }
@@ -103,12 +118,20 @@ function Test-Signature([string]$dir, [string]$fingerprint) {
$gh = Join-Path ([System.IO.Path]::GetTempPath()) ("b2m-" + [guid]::NewGuid().ToString("N").Substring(0, 8))
New-Item -ItemType Directory -Force -Path $gh | Out-Null
try {
- $env2 = @{ GNUPGHOME = $gh }
- # No agent is needed to check a signature; a failed import shows up as a failed verification below.
- $null = Invoke-Native $gpg.Source @("--batch", "--quiet", "--no-autostart", "--import", (Join-Path $dir "release-signing-key.asc")) $env2
- $ver = Invoke-Native $gpg.Source @("--batch", "--no-autostart", "--status-fd", "1", "--verify", (Join-Path $dir "SHA256SUMS.txt.asc"), (Join-Path $dir "SHA256SUMS.txt")) $env2
+ # Forward slashes work for both Gpg4win and the MSYS gpg that ships with Git for Windows; a
+ # backslash GNUPGHOME is not understood by the MSYS build. --homedir avoids the environment entirely.
+ $home2 = $gh -replace '\\', '/'
+ $key = (Join-Path $dir "release-signing-key.asc") -replace '\\', '/'
+ $sig = (Join-Path $dir "SHA256SUMS.txt.asc") -replace '\\', '/'
+ $sums = (Join-Path $dir "SHA256SUMS.txt") -replace '\\', '/'
+ $imp = Invoke-Native $gpg.Source @("--homedir", $home2, "--batch", "--quiet", "--import", $key)
+ $ver = Invoke-Native $gpg.Source @("--homedir", $home2, "--batch", "--status-fd", "1", "--verify", $sig, $sums)
$ok = $ver.Output -split "`n" | Where-Object { $_ -like "*VALIDSIG *" -and ($_.Trim() -split " ")[-1] -eq $fingerprint }
- if (-not $ok) { throw "the signature on SHA256SUMS.txt did not verify against the pinned key $fingerprint. Nothing was installed." }
+ if (-not $ok) {
+ Write-Output " gpg ($($gpg.Source)) import: exit $($imp.ExitCode) $($imp.Error.Trim())"
+ Write-Output " gpg verify: exit $($ver.ExitCode) $($ver.Error.Trim())"
+ throw "the signature on SHA256SUMS.txt did not verify against the pinned key $fingerprint. Nothing was installed."
+ }
Write-Output (" signature: OK (SHA256SUMS.txt signed by key " + $fingerprint.Substring(0, 8) + "..." + $fingerprint.Substring($fingerprint.Length - 8) + ")")
} finally { Remove-Item -Recurse -Force $gh -ErrorAction SilentlyContinue }
}
@@ -137,14 +160,23 @@ function Install-App([string]$app, [string]$plat, [string]$stage) {
$x = Join-Path $stage "x-$app"
Add-Type -AssemblyName System.IO.Compression.FileSystem
[System.IO.Compression.ZipFile]::ExtractToDirectory((Join-Path $stage $asset.file), $x)
- $top = Get-ChildItem -Path $x -Directory | Select-Object -First 1
- if (-not $top) { throw "$($asset.file) had no folder inside" }
- if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }
- Move-Item -Path $top.FullName -Destination $dest
- Get-ChildItem -Path $dest -Recurse -File | Unblock-File -ErrorAction SilentlyContinue
+ $tops = @(Get-ChildItem -LiteralPath $x -Directory | Where-Object { $_.Name -ne "__MACOSX" })
+ if ($tops.Count -ne 1) { throw "$($asset.file) should hold exactly one top-level folder; found $($tops.Count)" }
+ Set-Claim $a.name
+ $old = "$dest.old"
+ if (Test-Path -LiteralPath $old) { Remove-Item -LiteralPath $old -Recurse -Force }
+ # Keep the previous version until the new one proves it runs, so a failed upgrade loses nothing.
+ if (Test-Path -LiteralPath $dest) { Move-Item -LiteralPath $dest -Destination $old }
+ Move-Item -LiteralPath $tops[0].FullName -Destination $dest
+ Get-ChildItem -LiteralPath $dest -Recurse -File | Unblock-File -ErrorAction SilentlyContinue
Write-Output " windows: cleared any download block flag on the files (Unblock-File)"
$ver = Invoke-Native $cli @("--version")
- if ($ver.ExitCode -ne 0) { throw "$cli was installed but does not run. Try: & `"$cli`" --version" }
+ if ($ver.ExitCode -ne 0) {
+ Remove-Item -LiteralPath $dest -Recurse -Force
+ if (Test-Path -LiteralPath $old) { Move-Item -LiteralPath $old -Destination $dest }
+ throw "$cli was installed but does not run, so the previous version (if any) was kept. Try: & `"$cli`" --version"
+ }
+ if (Test-Path -LiteralPath $old) { Remove-Item -LiteralPath $old -Recurse -Force }
[System.IO.File]::WriteAllText($stamp, $a.version + "`n", $Utf8)
Write-Launcher $a; Add-ToManifest $a.name
Write-Output "${app}: done, $(($ver.Output -split "`n")[0].Trim()), $(Get-SizeMB $dest) MB on disk"
@@ -153,12 +185,14 @@ function Install-App([string]$app, [string]$plat, [string]$stage) {
function Write-Launcher($a) {
# Relative to the .cmd, so the folder can move. Pure ASCII, so any user name works.
New-Item -ItemType Directory -Force -Path (Join-Path $HomeDir "bin") | Out-Null
+ Set-Claim "bin/$($a.name)-cli.cmd"
$text = "@echo off`r`n`"%~dp0..\$($a.name)\$($a.name)-cli.exe`" %*`r`n"
[System.IO.File]::WriteAllText((Join-Path $HomeDir "bin\$($a.name)-cli.cmd"), $text, (New-Object System.Text.UTF8Encoding($false)))
Add-ToManifest "bin/$($a.name)-cli.cmd"
}
function Copy-SupportFiles {
+ Set-Claim "versions.json"; Set-Claim "recipes"
Copy-Item (Join-Path $Pack "versions.json") (Join-Path $HomeDir "versions.json") -Force
$rec = Join-Path $HomeDir "recipes"
if (Test-Path $rec) { Remove-Item -Recurse -Force $rec }
diff --git a/plugin/skills/brief2mp4/edit/install_edit.sh b/plugin/skills/brief2mp4/edit/install_edit.sh
index c163549..b00c9f1 100755
--- a/plugin/skills/brief2mp4/edit/install_edit.sh
+++ b/plugin/skills/brief2mp4/edit/install_edit.sh
@@ -146,8 +146,20 @@ manifest_add() { # manifest_add <relative path>: remember what this installer cr
grep -qxF "$1" "$MANIFEST" || printf '%s\n' "$1" >> "$MANIFEST"
}
+in_manifest() { [[ -f "$MANIFEST" ]] && grep -qxF "$1" "$MANIFEST"; }
+
+claim() { # claim <relative path>: before writing it, move aside anything there this installer did not create
+ local rel="$1" aside
+ if [[ -e "$HOME_DIR/$rel" || -L "$HOME_DIR/$rel" ]] && ! in_manifest "$rel"; then
+ aside="$HOME_DIR/$rel.backup-$(date +%Y%m%d-%H%M%S)"
+ mv "$HOME_DIR/$rel" "$aside"
+ say " kept your existing $rel at $aside (it was not created by this installer)"
+ fi
+}
+
write_launcher() { # write_launcher <cli name> <relative cli path>; relative, so the folder can move
mkdir -p "$HOME_DIR/bin"
+ claim "bin/$1"
cat > "$HOME_DIR/bin/$1" <<LAUNCH
#!/usr/bin/env bash
# brief2mp4 edit pack launcher. Paths are relative to this file, so the folder can move.
@@ -161,6 +173,7 @@ LAUNCH
}
copy_support_files() { # everything the installed pack needs, so it never reads from the clone
+ claim "versions.json"; claim "recipes"
cp "$PACK/versions.json" "$HOME_DIR/versions.json"
rm -rf "${HOME_DIR:?}/recipes"; mkdir -p "$HOME_DIR/recipes"
cp "$PACK"/recipes/* "$HOME_DIR/recipes/"
@@ -186,14 +199,21 @@ install_app() { # install_app <app> <platform>
verify_hash "$STAGE/$file" "$file" "$STAGE/SHA256SUMS.txt" "$sha"
verify_signature "$STAGE" "$(vget "$app" fingerprint)"
unpack "$STAGE/$file" "$STAGE/x"
- top="$(find "$STAGE/x" -mindepth 1 -maxdepth 1 -type d | head -1)"
- [[ -n "$top" ]] || die "$file had no folder inside"
- rm -rf "${dest:?}.new"; mv "$top" "$dest.new"
- if [[ -d "$dest" ]]; then rm -rf "${dest:?}"; fi
+ local tops; tops="$(find "$STAGE/x" -mindepth 1 -maxdepth 1 -type d | grep -v '/__MACOSX$' || true)"
+ [[ "$(printf '%s\n' "$tops" | grep -c .)" == 1 ]] || die "$file should hold exactly one top-level folder; found: $(printf '%s ' $tops)"
+ top="$tops"
+ claim "$name"
+ rm -rf "${dest:?}.new" "${dest:?}.old"; mv "$top" "$dest.new"
+ # Keep the previous version until the new one proves it runs, so a failed upgrade loses nothing.
+ if [[ -d "$dest" ]]; then mv "$dest" "$dest.old"; fi
mv "$dest.new" "$dest"
chmod +x "$cli" 2>/dev/null || true
strip_quarantine "$cli"
- "$cli" --version >/dev/null 2>&1 || die "$cli was installed but does not run. Try: $cli --version"
+ if ! "$cli" --version >/dev/null 2>&1; then
+ rm -rf "${dest:?}"; [[ -d "$dest.old" ]] && mv "$dest.old" "$dest"
+ die "$cli was installed but does not run, so the previous version (if any) was kept. Try: $cli --version"
+ fi
+ rm -rf "${dest:?}.old"
printf '%s\n' "$ver" > "$dest/.b2m-version"
write_launcher "$name-cli" "$(rel_cli "$name" "$plat")"; manifest_add "$name"
say "$app: done, $("$cli" --version | head -1), $(size_mb "$dest") MB on disk"
diff --git a/tests/test_cli_detect.py b/tests/test_cli_detect.py
index f371f76..f1a7efb 100644
--- a/tests/test_cli_detect.py
+++ b/tests/test_cli_detect.py
@@ -139,3 +139,32 @@ def test_public_repo_hygiene():
hits += [f"{path.relative_to(REPO)}: {b}" for b in banned if b.lower() in text.lower()]
assert not hits, hits
assert max(len(p.read_text(encoding="utf-8").splitlines()) for p in files if p.suffix in {".py", ".js", ".mjs", ".sh", ".md"}) < 800
+
+
+@posix_only
+def test_3d_installer_never_adopts_or_deletes_a_users_folder(tmp_path):
+ """An existing folder with the user's files must be refused at install and left alone at uninstall."""
+ folder = tmp_path / "myproj"
+ folder.mkdir()
+ (folder / "thesis.txt").write_text("precious", encoding="utf-8")
+ env = {**os.environ, "B2M3D_HOME": str(folder)}
+ installer = str(PACK / "install_3d.sh")
+ inst = subprocess.run([BASH, installer, "--components", "core"], env=env, capture_output=True, text=True)
+ assert inst.returncode != 0 and "not created by this installer" in inst.stderr
+ assert not (folder / ".installed-by-brief2mp4-3d").exists()
+ unin = subprocess.run([BASH, installer, "--uninstall"], env=env, capture_output=True, text=True)
+ assert unin.returncode != 0
+ assert (folder / "thesis.txt").read_text(encoding="utf-8") == "precious"
+
+
+@posix_only
+def test_3d_uninstall_keeps_files_it_did_not_create(tmp_path):
+ """Uninstall removes only the pack's own entries; a file the user added stays, and so does the folder."""
+ home = tmp_path / "home"
+ (home / "venv").mkdir(parents=True)
+ (home / ".installed-by-brief2mp4-3d").write_text("x", encoding="utf-8")
+ (home / "notes.txt").write_text("mine", encoding="utf-8")
+ env = {**os.environ, "B2M3D_HOME": str(home)}
+ run = subprocess.run([BASH, str(PACK / "install_3d.sh"), "--uninstall"], env=env, capture_output=True, text=True)
+ assert run.returncode == 0
+ assert not (home / "venv").exists() and (home / "notes.txt").read_text(encoding="utf-8") == "mine"