Check for Updates (Environment Manager)
All environment logic is written only in this Skill: skills version, runtime installation and health check. Business Skills at step 0 reference the "Readiness Check" below with a single line, and do not carry any environment logic themselves—if the environment strategy changes, only this file needs to be modified. This Skill does not create projects, open Studio, or transcribe any media.
Readiness Check (Business Skill's Step 0 runs from here)
Process in three steps, output one of three states: Ready / Needs New Session / Stop.
1. Locate Current Plugin Cache (read-only)
Locate from the actual source file path of this Skill provided by the host: go up two levels from this file's directory to get
<Plugin Root>. Use a file reading tool to confirm that <Plugin Root>/.codex-plugin/plugin.json and
<Plugin Root>/scripts/check-plugin-update.cjs both exist. If the path is unavailable, the directory structure does not match, or the files do not exist,
stop the update comparison with installed_identity_missing; do not call the user's
CODEX_HOME to run codex plugin list to guess, and do not search the entire disk.
All subsequent commands use this literal path for <Plugin Root> (wrap the entire path in quotes if it contains spaces).
Command blocks must not use shell variables or command substitution—bash and PowerShell assignment syntaxes 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 the user's Marketplace CLI output.
2. Are Skills Up-to-Date?
node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace chengfeng-videocut --json
(Marketplace name defaults to chengfeng-videocut; use the user's custom name if they have configured one.)
current→ proceed to step 3update_available_confirmation_required→ displayinstalled,candidate, and four candidate attributes: version, 40-hexsnapshotRevision(B), 40-hexcontentRevision(A),publisherChecksum(SHA-256), stop and wait for user confirmation; after confirmation, proceed to the "Activation" section below. Activation success = Needs New Session: skill text is loaded at session start, mid-session updates do not take effect for the current session, ask the user to start a new session to continue the task- If
legacyInstalledIdentity=trueis also present, this is a one-time compatibility migration from historical 0.10.5 to the new proof format; still use the same confirmation gate, do not require the user to modify the Marketplace ref in advance
- If
marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe→ current user Marketplace is missing, source is untrusted, or not an exact 40-hex pin; do not call the user's Codex CLI to fix, report and continue to step 3installed_identity_missing/installed_identity_untrusted→ current cache identity cannot be safely read or proven, do not guess version, do not activate; report and continue to step 3installed_context_mismatch→ the real cache path, Marketplace name, or explicitCODEX_HOMEof the current Skill is inconsistent; do not search other caches, do not activateisolated_stage_failed/isolated_stage_schema_invalid/isolated_cleanup_failed→ temporary candidate staging, CLI schema, or temporary directory cleanup failed; user HOME has zero writes, report and continue to step 3update_metadata_untrusted→ the proof of version + B + A + SHA-256 is invalid, do not activate; report and continue to step 3candidate_older_than_installed→ downgrading is prohibited, report and continue to step 3- Network unreachable or other check errors → explain briefly to the user, continue to step 3 with the current runtime check— a failed update check does not block work
Normal checks are only allowed to discover candidates using the official stable ref in a temporary CODEX_HOME; for the user's
CODEX_HOME, do not call any codex commands and do not write configurations, Marketplace, or cache.
All version directories in the current cache must be strict semver; lower versions may remain but only the single highest
semver priority is considered active. If multiple directories with the same priority exist at the highest position, return
installed_identity_untrusted, do not select by directory name lexicographic order.
3. Is the Runtime Compatible?
node "<Plugin Root>/scripts/ensure-runtime.cjs" --install-if-missing --json
ready→ Ready, business skill continuesruntime.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 additional dependencies or starting new servicesruntime.kind=managed/path/sourceare still compatible CLI installation sources; subsequent business contracts are the same
- missing: the script prompts only once "Installing from GitHub Release", auto-resumes after SHA-256 verification completes
runtime_unhealthy, installation failure, or post-install doctor failure → Stop, report structured diagnostics. Stop means stop: do not proceed with any alternative interface like custom review pages, players, timelines, or any other substitute workflows. Output produced when the product is unusable is untrustworthy (real case: when Runtime was missing, an Agent handcrafted a "review panel" webpage whose review decisions were completely incompatible with the product's ledger format, causing the user to redo everything). The correct action is only one: provide structured diagnostics to the user, guide them to install or report an Issueruntime_capability_missing→ Stop: Runtime is healthy but below the contract requirements. Report both version numbers and the difference, guide the user to upgrade after confirmation (upgrade replaces~/.chengfeng-videocut/app, project data remains untouched); do not modify the existing installation until user confirms, prohibit falling back to old editing chains- During the readiness check, do not start services, open Studio, or create projects
Machine Prerequisites
Supports macOS and Windows 10/11, with two installation paths:
Desktop App (Recommended)
Install and launch Chengfeng VideoCut at least once
-> App bundles Bun, FFmpeg, FFprobe, and Runtime
-> Does not require the user to add these tools to the system PATH
-> Skills reuse the same service via the stable entry at ~/.chengfeng-videocut/bin
Pure CLI Installation
macOS brew install bun ffmpeg
Windows winget install Oven-sh.Bun Gyan.FFmpeg
Open a new terminal/session after installation for PATH to take effect
Both paths still require Node.js ≥ 20 to run Plugin scripts; exporting subtitles/animations still requires Google
Chrome. Pure CLI users install manually, Windows users can use
winget install OpenJS.NodeJS.LTS Google.Chrome. Must explicitly stop if items are missing, do not silently skip.
Git is also required for Skills update identity self-proof; Windows can use winget install Git.Git. If Git is not executable or
cannot read the official snapshot's origin/HEAD/commit relationships, the update check fails closed, but still continues to the
Runtime check according to the rules above.
Cloud transcription additionally requires Volcengine credentials: node "<Plugin Root>/scripts/videocut-cli.cjs" config set transcription.apiKey <key>.
See the detailed agreement in Runtime and Product Contract.
Skills Update: Inspect and Activate
Read-only inspection of the current Plugin cache: no network access, no codex calls, no writes to user
CODEX_HOME:
node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace "<Marketplace Name>" --inspect --json
Success returns inspected_no_refresh, containing only the current pinned Marketplace and cache identity, without generating
remote candidates.
Network-isolated check (when user explicitly says "check for updates," or step 2 of the readiness check):
node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace "<Marketplace Name>" --json
current: reports the installed identity and the latest published identity found in the temporary environment.update_available_confirmation_required: displays installed and candidate four attributes: version,snapshotRevision(B),contentRevision(A),publisherChecksum; stops and waits for user confirmation.legacyInstalledIdentity=true: the current cache is a compatible historical 0.10.5 cache. It can enter the normal confirmation flow above; the old identity is bound together by Marketplace exact revision, cache directory version, manifest version, and inventory digest. Do not ask the user to change the ref first, and do not create a separate "migration succeeded" status.marketplace_not_found/marketplace_source_untrusted/marketplace_ref_unsafe: current user Marketplace is missing, untrusted, or not pinned to its own exact 40-hex revision; do not auto-change the ref.installed_identity_missing/installed_identity_untrusted: current cache is unrecognizable or untrustable, 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_HOMEis inconsistent with the HOME to which the cache belongs; do not cross-directory guess.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 proof of B, A, SHA-256/manifest recomputation, or the identities of manifest, Marketplace revision, and provenance contradict each other.candidate_older_than_installed: downgrading from a newer local version is prohibited.- Any snapshot/parse/version errors: keep structured JSON; user HOME
userMutationPerformed=false.
The script only executes the official Marketplace CLI in a newly created temporary CODEX_HOME: first use
marketplace add Agentchengfeng/chengfeng-videocut-skills --ref stable to establish the discovery source,
then use marketplace upgrade to materialize the snapshot in the same temporary HOME, and finally
plugin list to obtain the candidate. The 40-hex B resolved from stable, the 40-hex A from the provenance,
manifest version, and recomputable 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
A→B Plugin subtree only changes provenance. The temporary directory is deleted after use. The user's HOME Marketplace must remain at the
previously confirmed exact B; during the check phase, not even a read-only codex command is called on it.
On Windows, when resolving codex / git, first search for executable extensions according to PATHEXT, then try files without
extensions; .cmd / .bat are wrapped via ComSpec. Therefore, a Unix codex shim in the same directory as pnpm
will not shadow codex.cmd.
Activate Only After User Explicitly Confirms
Confirmation must occur only after the user has seen the exact candidate version, B, A, and checksum:
node "<Plugin Root>/scripts/check-plugin-update.cjs" --marketplace "<Marketplace Name>" --activate --confirmed --expected-version "<Displayed Version>" --expected-snapshot-revision "<Displayed B>" --expected-content-revision "<Displayed A>" --expected-sha256 "<Displayed Package SHA256>" --json
The script must recreate a temporary CODEX_HOME, stage the candidate from stable again, and compare all four
attributes against all --expected-* arguments. If the candidate drifts between staging rounds or the parameters do not match, return
confirmation_mismatch, user HOME has zero writes. After passing, record the exact pre-update snapshot revision
and cache identity, then use only official commands on the user's HOME:
plugin marketplace remove <Marketplace Name>
plugin marketplace add Agentchengfeng/chengfeng-videocut-skills --ref <B>
plugin marketplace upgrade <Marketplace Name>
<B> must be the 40-hex snapshotRevision just re-staged and confirmed with the user;
stable, other branches, tags, short SHAs, or any different ref all return
marketplace_ref_unsafe. After upgrade, the script directly re-reads and verifies version + B + A +
SHA-256 from the cache; only if all match exactly does it return activated. After successful activation, inform the user to
restart Codex or start a new session.
If --confirmed is missing, return confirmation_required; if any expected field is missing, different, or drifts after
re-staging, return confirmation_mismatch; both keep user HOME zero writes.
Before entering the first write command, the script re-reads the user's Marketplace and active cache with CAS. If they differ
from the old identity saved before staging, return activation_state_changed, activation does not start and user HOME
has zero writes. If any step of the write transaction fails, the script first checks the post-state of Marketplace and cache:
activation_failed_no_change: on failure, still exactly equals old identity; no rollback needed,userMutationPerformed=falseactivation_failed_rolled_back: candidate activation failed, but the old exact revision and old cache are fully restoredactivation_cache_locked_rolled_back: failure identified as cache/file handle lock, and old state is fully restoredactivation_failed_rollback_incomplete: rollback failed, or unable to prove both Marketplace and cache have returned to the old identity; report the actual post-state and stop
Only when the post-state has changed, use the saved old exact revision to perform official remove → add
--ref <old B> → upgrade rollback, and again directly re-read the cache. The above failure states cannot say
"updated." Do not manually copy or delete cache 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 getting "Ready," run the full self-check and report 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 for installation;
transcription credentials guide for 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 package and do not require
modifying the system PATH. After everything is set up, tell the user: just say "cut a podcast" to start.
Boundaries
- Plugin version and Runtime version are independent; minimum Runtime compatibility and Release targets are controlled by the
runtime-requirements.jsoncontract, no version numbers are hardcoded in this document stableis only used for temporary discovery; do not write it as a persistent ref for user installation, and do not refer to temporary staging, legacy cache, or local directories as activated versions- During the update check phase, zero Codex calls and zero writes to user HOME; activation with rollback can only begin after the user sees and confirms version + B + A + SHA-256
- Do not publish, modify project data, or media; official Codex activation after user confirmation and Runtime installation are the only write exceptions
- 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