Check Updates (Environment Manager)
All environment logic is written exclusively in this skill: skills version, Runtime installation and health checks. Business skills call the readiness check below as their Step 0 and carry no environment logic themselves — if the environment strategy changes, only this file is modified.
This skill does not create projects, open Studio, or transcribe any media.
Readiness Check (Business Skills Execute Step 0 from Here)
Three steps, output one of three states: Ready / New Session Required / Stop.
1. Locate Current Plugin Cache (Read-Only)
Locate from the actual source file path of this skill provided by the host: the directory two levels up from this file is <plugin root>. Use file read tools to confirm that <plugin root>/.codex-plugin/plugin.json and <plugin root>/scripts/check-plugin-update.cjs both exist. If the path is unavailable, directory level is wrong, or files are missing, stop the update comparison with installed_identity_missing; do not call codex plugin list under the user's CODEX_HOME to guess, and do not search the entire disk.
In all subsequent commands, <plugin root> is substituted with this literal path (wrap the whole segment in quotes if it contains spaces). Command blocks must not use shell variables or command substitution — the assignment syntax of bash and PowerShell are incompatible. The check script reads the installed manifest, provenance, Marketplace exact revision, and bundle digest directly from its own cache; the check phase does not depend on user Marketplace CLI output.
2. Are Skills Up-to-Date
node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json
(The Marketplace name defaults to chengfeng-videocut; if the user has configured a different name, use that one.)
current→ Continue to Step 3update_available_confirmation_required→ Showinstalled,candidate, and the four candidate fields: version, 40-hexsnapshotRevision(B), 40-hexcontentRevision(A),publisherChecksum(SHA-256). Stop and wait for user confirmation; after confirmation, go to the "Activation" section below. Activation success = New Session Required: the skill text is loaded at session start, so mid-session updates do not take effect in this session; ask the user to open a new session and then continue the task.- If
legacyInstalledIdentity=true, this indicates a one-time compatibility migration from historical 0.10.5 to the new provenance format; still use the same confirmation gate, do not require the user to pre-modify the Marketplace ref.
- If
marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe→ The current user Marketplace is missing, the source is untrusted, or the ref is not an exact 40-hex pin; do not call user Codex CLI to fix, report and continue to Step 3.installed_identity_missing/installed_identity_untrusted→ The current cache identity cannot be safely read or attested; do not guess version, do not activate; report and continue to Step 3.installed_context_mismatch→ The actual cache path of this skill, Marketplace name, or explicitCODEX_HOMEis inconsistent; do not search other caches, do not activate.isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed→ Temporary candidate staging, CLI schema, or temporary directory cleanup failed; user HOME is zero-written, report and continue to Step 3.update_metadata_untrusted→ The version + B + A + SHA-256 attestation does not hold; do not activate; report and continue to Step 3.candidate_older_than_installed→ Downgrade prohibited, report and continue to Step 3.- Network unreachable or other check error → Explain briefly to the user, then continue with the current Runtime check to Step 3 — a failed update check does not block work.
Normal checking only allows discovering candidates in a temporary CODEX_HOME using the official stable ref; do not call any codex commands against the user's CODEX_HOME, and do not write configuration, Marketplace, or cache. The version directories of the current cache must all be strict semver; lower versions may remain, but only the single highest semver precedence is considered active. If a tie exists at the highest position, return installed_identity_untrusted; do not pick by alphabetical order of directory names.
3. Is Runtime Compatible
node "<plugin root>/scripts/ensure-runtime.cjs" --install-if-missing --json
ready→ Ready, business skills continue.runtime.kind=desktop-managedindicates the desktop App has installed the bundled Runtime, Bun, FFmpeg, and FFprobe into the Product's unified managed directory; Skills reuse them directly without installing extra dependencies or starting additional services.runtime.kind=managed/path/sourceare still compatible CLI installation sources; the subsequent business contract is the same.
- missing: The script only prompts once "Installing from GitHub Release", and automatically re-runs after SHA-256 verification completes.
runtime_unhealthy, installation failure, or post-install doctor failure → Stop, report structured diagnostics. Stop means stop: do not continue the workflow with a self-made review page, player, timeline, or any alternative interface. Any output produced when the product is unusable is untrustworthy (real case: when the Runtime was missing, an Agent hand-crafted a "review desk" webpage whose review decisions were completely incompatible with the product's ledger format, making the user's work useless). The only correct action: present structured diagnostics to the user, guiding them to install or report an issue.runtime_capability_missing→ Stop: Runtime is healthy but below the contract requirements. Report the two version numbers and the difference, guide the user to confirm and then upgrade (the upgrade replaces~/.chengfeng-videocut/app, project data is unchanged); do not touch the existing installation before user confirmation, prohibit falling back to old editing chains.- During the readiness check phase, do not start services, open Studio, or create projects.
Machine Prerequisites
Supports macOS and Windows 10/11, with two installation paths:
Desktop (recommended)
Install and launch Chengfeng VideoCut at least once
-> The App bundles Bun, FFmpeg, FFprobe, and Runtime
-> The user does not need to add these tools to the system PATH
-> Skills reuse the same service via the stable entry point at ~/.chengfeng-videocut/bin
Pure CLI
macOS brew install bun ffmpeg
Windows winget install Oven-sh.Bun Gyan.FFmpeg
After installation, open a new terminal/session for PATH to take effect
Both paths still require Node.js ≥ 20 to execute Plugin scripts; exporting subtitles/animation still requires Google Chrome. Pure CLI users install these themselves; Windows users can run winget install OpenJS.NodeJS.LTS Google.Chrome. Missing items must cause a clear stop, not a silent skip.
Skills update identity self-attestation also requires Git; Windows users can run winget install Git.Git. If Git is not executable or cannot read the origin/HEAD/commit relationships of the official snapshot, the update check fails closed, but still proceeds to Runtime checking according to the rules above.
Cloud transcription additionally requires Volcengine credentials: node "<plugin root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>.
For detailed protocol, see Runtime and Product Contract.
Skills Update: Inspect and Activate
Read-only inspection of the current Plugin cache: no network, no codex calls, no writes to the user's CODEX_HOME:
node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace "<market name>" --inspect --json
On success, returns inspected_no_refresh, containing only the currently pinned Marketplace and cache identity; no remote candidate is generated.
Isolated check with network (user explicitly says "check for updates", or readiness check Step 2):
node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace "<market name>" --json
current: Reports the installed and the latest published identity found in the temporary environment.update_available_confirmation_required: Shows installed and candidate four fields: version,snapshotRevision(B),contentRevision(A),publisherChecksum; stops and waits for user confirmation.legacyInstalledIdentity=true: This is a compatible historical 0.10.5 cache. It can enter the normal confirmation flow above; the legacy identity is bound by Marketplace exact revision, cache directory version, manifest version, and inventory digest together. Do not ask the user to change ref first, and do not invent a separate "migration successful" state.marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe: The current user Marketplace is missing, untrusted, or not pinned to its own exact 40-hex revision; do not auto-change ref.installed_identity_missing/installed_identity_untrusted: The current cache is unrecognizable or untrustworthy; do not guess the installed version.installed_context_mismatch: The script execution location is not the single highest active cache of the current Marketplace, or the explicitCODEX_HOMEdoes not match the HOME of that cache; do not guess across directories.isolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed: Only states that temporary staging, CLI JSON schema, or cleanup failed; do not imply the user's installation has been refreshed.update_metadata_untrusted: The temporary snapshot lacks B, A, SHA-256/manifest re-computation attestation, or the identities from manifest, Marketplace revision, and provenance contradict each other.candidate_older_than_installed: Downgrade from a newer local version is prohibited.- Any snapshot/parse/version error: Preserve structured JSON; user HOME
userMutationPerformed=false.
The script only executes the official Marketplace CLI in a newly created temporary CODEX_HOME: first adds the discovery source with marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable, then within the same temporary HOME runs marketplace upgrade to materialize a snapshot, and uses plugin list to retrieve the candidate. The 40-hex B resolved from stable, the 40-hex A from provenance, the manifest version, and the re-computable SHA-256 together constitute the candidate. Git must also prove that the temporary Marketplace origin is the official repository, HEAD=B, A is an ancestor of B, the Plugin working tree is clean, and the Plugin sub-tree from A→B only changes provenance. The temporary directory is deleted after use. The user HOME Marketplace must remain at the previously confirmed exact B; not even a read-only codex command is called against it during the check phase.
On Windows, when resolving codex / git, first look up executable extensions via PATHEXT, then try the file without extension; .cmd / .bat are wrapped via ComSpec. This prevents a Unix codex shim in the same pnpm directory from shadowing codex.cmd.
Activation Only After Explicit User Confirmation
Confirmation must occur after the user has seen the exact candidate version, B, A, and checksum:
node "<plugin root>/scripts/check-plugin-update.cjs" --marketplace "<market name>" --activate --confirmed --expected-version "<shown version>" --expected-snapshot-revision "<shown B>" --expected-content-revision "<shown A>" --expected-sha256 "<shown package SHA256>" --json
The script must recreate the temporary CODEX_HOME, stage a candidate from stable again, and compare all four fields with --expected-*. If the candidate drifts between staging and comparison, or any parameter mismatch, return confirmation_mismatch; user HOME is zero-written. On pass, record the exact snapshot revision and cache identity before the update, then execute against the user HOME using only official commands:
plugin marketplace remove <market name>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <market name>
<B> must be the exact 40-hex snapshotRevision that was re-staged and confirmed by the user; stable, other branches, tags, short SHA, or any different ref returns marketplace_ref_unsafe. After upgrade, the script re-reads directly from the cache and verifies version + B + A + SHA-256; only when all match exactly does it return activated. On activation success, inform the user to restart Codex or open a new session. If --confirmed is missing, return confirmation_required; if any expected field is missing, different, or if the re-staged candidate drifted, return confirmation_mismatch; both keep user HOME zero-written.
Before entering the first write command, the script re-reads the user Marketplace and active cache with CAS. If different from the old identity saved before staging, return activation_state_changed; activation does not start and user HOME is zero-written. If any write transaction step fails, the script checks the post-condition of the Marketplace and cache:
activation_failed_no_change: After failure, the state still exactly equals the old identity; no rollback needed,userMutationPerformed=false.activation_failed_rolled_back: Candidate activation failed, but the old exact revision and old cache have been fully restored.activation_cache_locked_rolled_back: Failure was identified as cache/file handle lock, and old state has been fully restored.activation_failed_rollback_incomplete: Rollback failed, or could not prove that both Marketplace and cache returned to the old identity; report the actual post-condition and stop.
Only if the post-condition has changed, use the saved old exact revision to execute the official remove → add --ref <old B> → upgrade rollback, and re-read the cache directly. None of these failure states may be reported as "already updated." Do not manually copy or delete caches to fake success; do not touch Runtime, projects, media, EDL, or Studio state.
User Says "Install Editing Environment / Install Player / Check Environment"
Run the full readiness check directly; after obtaining "Ready", run a full self-test and report results as-is:
node "<plugin root>/scripts/videocut-cli.cjs" doctor --json
Report: Runtime version and location, each doctor check result, how to fix missing items (machine dependencies guide installation; transcription credentials guide node "<plugin root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>). If runtime.kind=desktop-managed, explicitly state that Bun/FFmpeg/FFprobe come from the desktop bundle and do not require modifying the system PATH. After setup, tell the user: just say "Cut talking-heads" to start.
Boundaries
- Plugin version and Runtime version are independent; minimum compatibility and Release targets are controlled by the
runtime-requirements.jsoncontract; do not hardcode any version numbers in this document. stableis only used for temporary discovery; do not write it as a persistent ref in the user's installation, and do not refer to temporary staging, legacy cache, or local directory as an activated version.- During the check-update phase: zero Codex calls to user HOME, zero writes; activation with rollback can only start after the user has seen and confirmed version + B + A + SHA-256.
- Do not publish, modify project data or media; the only write exceptions are official Codex activation after user confirmation and Runtime installation.
- Do not search for Electron
.app, NSIS installation directories, or pass Electron resource paths to business skills; the desktop App is responsible for writing the stable Product entry point; Skills only recognize that entry point.