Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

Add Dependabot, CodeQL, PR-labeling, CI concurrency, and more (#130)

Shogo Kajiyama1494229256c1
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..930e60c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Something in a tool/script doesn't behave as documented
+title: ""
+labels: fix
+---
+
+**Tool/script and version**
+<!-- e.g. cut.py, ffmpeg-skill 0.16.13 (`node -p "require('ffmpeg-skill/package.json').version"` or `doctor --json`'s "version") -->
+
+**Command run**
+```
+<!-- the exact scripts/*.py invocation, flags included -->
+```
+
+**Expected behavior**
+
+
+**Actual behavior**
+<!-- the real error/output, not a paraphrase -->
+
+
+**`doctor --json` output** (if the bug might be FFmpeg-build-specific)
+```json
+
+```
+
+**OS / FFmpeg version**
+<!-- e.g. macOS 14, Homebrew ffmpeg 8.0 -->
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..f64e60f
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Security vulnerability
+ url: https://github.com/kajisho5/ffmpeg-skill/security/advisories/new
+ about: Please report vulnerabilities privately (see SECURITY.md) instead of a public issue.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..a7db60c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: A new tool, flag, or capability
+title: ""
+labels: feature
+---
+
+**What editing task can't this skill do today?**
+<!-- concrete request, e.g. "reframe with a tracked subject" -->
+
+**What would the command/flag look like?**
+```
+scripts/whatever.py INPUT --new-flag ... -o OUT
+```
+
+**Why can't an existing tool + flag combination already do this?**
+
+
+**Any relevant FFmpeg filter/encoder this would rely on?**
+<!-- if known -- helps scope whether it needs a doctor capability check -->
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..16c2ca5
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,15 @@
+# Keeps GitHub Actions pins (actions/checkout@v4, release-drafter@v6, etc.) and package.json's
+# npm metadata current, opening a PR for each update instead of letting either go stale silently.
+# There's no requirements.txt/pyproject.toml to watch here -- scripts/ is deliberately Python
+# 3.9 standard library only, no third-party runtime dependencies (see README).
+version: 2
+updates:
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "weekly"
+
+ - package-ecosystem: "npm"
+ directory: "/"
+ schedule:
+ interval: "weekly"
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..de1263e
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,12 @@
+## Summary
+
+<!-- What changed and why -- the "why" matters more than the "what" for anyone reading this
+ later. Link the issue/finding it addresses if there is one. -->
+
+## Test plan
+
+<!-- Evidence, not assertions: which tests you ran (and their result), what you verified live
+ if it can't be covered by a test, and anything intentionally left unverified for after
+ merge (mark with `[ ]`). -->
+
+- [ ]
diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml
index 0b9d772..0f01fa9 100644
--- a/.github/release-drafter.yml
+++ b/.github/release-drafter.yml
@@ -1,11 +1,15 @@
-# Config for release-drafter/release-drafter, used two ways:
+# Config for release-drafter/release-drafter, used three ways:
# - release-drafter.yml (the workflow) runs it live on every push to main, keeping a running
# DRAFT release as a human-readable cross-check -- this draft is never auto-published.
+# - release-drafter.yml *also* runs it on every PR open/reopen/sync, purely for `autolabeler`
+# below -- it applies fix/feature/major/chore labels to the PR itself from its title/files,
+# so a PR that merges without anyone manually labeling it still carries a real signal instead
+# of silently defaulting to patch every time.
# - release.yml runs it with dry-run: true to resolve the *actual* next version (via
# version-resolver below) whenever nobody bumped package.json by hand, then bumps the
-# version and writes CHANGELOG.md itself and releases for real. So the labels below (and
-# "default: patch" for an unlabeled PR) now drive real releases, not just this draft --
-# label a PR "minor"/"feature"/"major" when it needs more than a patch bump.
+# version and writes CHANGELOG.md itself and releases for real. So the labels below (whether
+# autolabeler applied them or a human did, and "default: patch" for anything still unlabeled)
+# now drive real releases, not just this draft.
name-template: "v$RESOLVED_VERSION"
tag-template: "v$RESOLVED_VERSION"
categories:
@@ -24,6 +28,29 @@ categories:
- ci
change-template: "- $TITLE (#$NUMBER)"
change-title-escapes: '\<*_&'
+autolabeler:
+ - label: "fix"
+ title:
+ - "/^fix/i"
+ - "/^Fix /"
+ - label: "feature"
+ title:
+ - "/^add/i"
+ - "/^feat/i"
+ - label: "major"
+ title:
+ - "/breaking/i"
+ body:
+ - "/BREAKING CHANGE/"
+ - label: "chore"
+ title:
+ - "/^chore/i"
+ - "/^ci:/i"
+ - "/^docs/i"
+ files:
+ - "*.md"
+ - "docs/**"
+ - ".github/**"
version-resolver:
major:
labels:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 66c991a..f71b2e0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -9,6 +9,15 @@ on:
pull_request:
push:
branches: [main]
+
+# A push while this is still running on the same PR/branch makes the old run pointless -- its
+# result is about to be superseded anyway. Cancelling it saves real money here: this matrix
+# includes macOS (10x the Ubuntu minute cost) and Windows (2x), so a few stacked pushes without
+# this can burn many times the minutes of the one push that actually mattered.
+concurrency:
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+ cancel-in-progress: true
+
jobs:
test:
strategy:
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..0afa72c
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,42 @@
+# Static analysis for the two languages actually shipped: Python (scripts/, mcp/, tests/) and
+# JavaScript (bin/install.js). Runs on every PR/push to main plus a weekly schedule so a query-pack
+# update can surface something new in code nobody touched recently. This repo has had a real,
+# manually-found vulnerability of exactly the kind CodeQL targets -- batch.py recipe steps
+# resolving outside scripts/ via an absolute path or `../` traversal (fixed in #124) -- so this is
+# a genuine second line of defense, not a checkbox.
+name: codeql
+
+on:
+ push:
+ branches: [main]
+ pull_request:
+ schedule:
+ - cron: "0 7 * * 1" # Mondays
+
+# See ci.yml's identical block for why: a superseded run's result is thrown away anyway, so
+# cancelling it saves real Actions minutes rather than just finishing a run nobody will read.
+concurrency:
+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+ cancel-in-progress: true
+
+permissions:
+ contents: read
+ security-events: write
+
+jobs:
+ analyze:
+ runs-on: ubuntu-latest
+ strategy:
+ fail-fast: false
+ matrix:
+ language: [python, javascript]
+ steps:
+ - uses: actions/checkout@v4
+
+ - uses: github/codeql-action/init@v3
+ with:
+ languages: ${{ matrix.language }}
+
+ - uses: github/codeql-action/analyze@v3
+ with:
+ category: "/language:${{ matrix.language }}"
diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml
new file mode 100644
index 0000000..4afdce4
--- /dev/null
+++ b/.github/workflows/dependabot-auto-merge.yml
@@ -0,0 +1,37 @@
+# Auto-approves and enables auto-merge (squash) for Dependabot PRs once CI is green, so a routine
+# actions/checkout@v4 -> v5 bump doesn't sit waiting on a human to click merge. Scoped to PRs
+# Dependabot itself opened (github-actions/npm ecosystem in dependabot.yml) -- this workflow never
+# runs for anyone else's PR. GitHub still requires any branch-protection-required checks to pass
+# before the auto-merge it enables here actually merges, so a red CI still blocks it as normal;
+# this only removes the "someone has to notice it's green and click merge" step.
+name: dependabot-auto-merge
+
+on:
+ pull_request_target:
+ types: [opened, reopened, synchronize]
+
+permissions:
+ contents: write
+ pull-requests: write
+
+jobs:
+ auto-merge:
+ if: github.actor == 'dependabot[bot]'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Fetch Dependabot metadata
+ id: metadata
+ uses: dependabot/fetch-metadata@v2
+ with:
+ github-token: ${{ secrets.GITHUB_TOKEN }}
+
+ # Only patch/minor updates auto-merge; a major bump (a breaking-change signal by semver
+ # convention) is left for a human to actually look at before it lands.
+ - name: Approve and enable auto-merge
+ if: steps.metadata.outputs.update-type != 'version-update:semver-major'
+ run: |
+ gh pr review --approve "$PR_URL"
+ gh pr merge --auto --squash "$PR_URL"
+ env:
+ PR_URL: ${{ github.event.pull_request.html_url }}
+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/release-drafter.yml b/.github/workflows/release-drafter.yml
index faf2e2d..3d99822 100644
--- a/.github/workflows/release-drafter.yml
+++ b/.github/workflows/release-drafter.yml
@@ -1,27 +1,34 @@
-# Keeps a draft GitHub Release up to date with merged-PR summaries as main moves forward. This is
-# purely a human-readable cross-check against CHANGELOG.md -- both the hand-written sections a PR
-# may still add itself and the ones release.yml now generates automatically -- and it never
-# publishes anything itself. release.yml is the one that actually decides and cuts a release; it
-# uses this same repo's release-drafter.yml config (via its own dry-run call) to resolve the next
-# version, it doesn't read this draft. See release.yml / README's "Development" -> "Releasing"
-# section for the real, fully-automated release flow.
+# Two jobs sharing one release-drafter config (.github/release-drafter.yml):
+# - update_release_draft (push to main): keeps a running DRAFT GitHub Release up to date with
+# merged-PR summaries -- a human-readable cross-check against CHANGELOG.md, never published
+# itself. release.yml is the one that actually decides and cuts a release (it uses this same
+# config via its own dry-run call); it doesn't read this draft.
+# - autolabel (PR opened/reopened/synchronized): applies release-drafter's `autolabeler` rules
+# (fix/feature/major/chore, from the PR's title and changed files) to the PR itself, so most
+# PRs carry a real label before they merge instead of silently defaulting to patch every time
+# in release.yml's version-resolver. pull_request_target (not pull_request) so a label can
+# still be applied on a PR from a fork, which only ever gets a GITHUB_TOKEN under this trigger.
#
-# push-to-main only, deliberately: release-drafter reads its config from the DEFAULT branch, so a
-# pull_request trigger fails with "Configuration file .github/release-drafter.yml is not found"
-# for any PR that hasn't merged yet (a chicken-and-egg problem for the very PR that first adds
-# this file, and for any PR opened before this config lands on main). The per-PR "next version"
-# preview a pull_request trigger would add isn't essential to what this workflow is actually for.
+# push-to-main only for the draft-release job, deliberately: release-drafter reads its config from
+# the DEFAULT branch, so running it on a PR that hasn't merged yet used to fail with "Configuration
+# file .github/release-drafter.yml is not found" (a chicken-and-egg problem for the very PR that
+# first added this file). That's resolved now that the config lives on main -- the autolabel job
+# below reads it the same way release-drafter always does, from main, regardless of what the PR
+# branch itself contains.
name: release-drafter
on:
push:
branches: [main]
+ pull_request_target:
+ types: [opened, reopened, synchronize]
permissions:
contents: read
jobs:
update_release_draft:
+ if: github.event_name == 'push'
permissions:
contents: write
pull-requests: write
@@ -30,3 +37,17 @@ jobs:
- uses: release-drafter/release-drafter@v6
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+ autolabel:
+ if: github.event_name == 'pull_request_target'
+ permissions:
+ contents: read
+ pull-requests: write
+ runs-on: ubuntu-latest
+ steps:
+ # The dedicated autolabeler sub-action (not the main release-drafter action used above) --
+ # applies just the `autolabeler` rules from release-drafter.yml to this PR, with nothing
+ # else running (no draft-release read/write against a PR ref that isn't main).
+ - uses: release-drafter/release-drafter/autolabeler@v7
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
index 503496b..9eb9a8d 100644
--- a/README.md
+++ b/README.md
@@ -395,7 +395,7 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai
`tests/test_contract.py` runs on all three OSes, but a handful of its tests build a fake `ffmpeg` as a `#!/bin/sh` script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through `doctor`'s parser — that technique isn't portable to Windows, so `test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class (fixture-driven layout parsing) are individually `skipIf`'d there and show as `skipped`, not silently absent, in the Windows job's log. Everything else — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract, including `cut.py`'s provenance fields — runs against the real Windows `ffmpeg` on every PR. See [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.
-**Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it asks [release-drafter](.github/release-drafter.yml) to resolve the next version from the labels on every PR merged since the last tag (`major`/`minor`/`feature`/`enhancement`/`fix`/`bug`/... — an unlabeled PR defaults to `patch`), bumps `package.json` and `docs/contract.md`, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.
+**Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it asks [release-drafter](.github/release-drafter.yml) to resolve the next version from the labels on every PR merged since the last tag (`major`/`minor`/`feature`/`enhancement`/`fix`/`bug`/... — an unlabeled PR defaults to `patch`). Most PRs don't need a label added by hand: `release-drafter.yml`'s `autolabel` job applies one automatically from the PR's title/changed files (`Fix ...` → `fix`, `Add ...`/`feat ...` → `feature`, `docs`/`.md`/`.github/` changes → `chore`) as soon as it's opened — add a label yourself only to override that, or for `major`. It bumps `package.json` and `docs/contract.md`, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.
Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -404,6 +404,7 @@ Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
| | |
|---|---|
| [CONTRIBUTING.md](CONTRIBUTING.md) | scope, dev setup, tests, PR expectations |
+| [SECURITY.md](SECURITY.md) | how to report a vulnerability privately |
| [SKILL.md](SKILL.md) | what the agent reads: workflow, request → tool map, audio-only rules, report format, pitfalls |
| [references/scripts.md](references/scripts.md) | per-flag reference for every tool |
| [references/devices.md](references/devices.md) | real-device notes (iPhone HDR, GoPro, DJI, screen recordings) |
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..6407793
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,22 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately using GitHub's [Report a vulnerability](../../security/advisories/new)
+flow (Security tab → Advisories → "Report a vulnerability") rather than a public issue or PR.
+That opens a private advisory only maintainers can see until a fix is ready.
+
+Include, where you can:
+- The affected file/tool (e.g. `scripts/batch.py`) and version
+- A minimal reproduction (input that triggers it, and what happens)
+- The impact you'd expect (e.g. arbitrary file write, path traversal, injection into an ffmpeg
+ filter graph)
+
+This project has had real findings fixed this way before -- e.g. `batch.py` recipe steps that
+could resolve outside `scripts/` via an absolute path or `../` traversal (fixed in #124). That
+kind of report is exactly what this process is for.
+
+## Supported versions
+
+Only the latest published version (see [CHANGELOG.md](CHANGELOG.md) / the latest npm release) is
+supported. There's no LTS branch -- please upgrade before reporting if you're on an older one.