brew-cask: structured file operation must use staged_path

Error message

brew-cask: structured file operation must use staged_path

What it means

`resolve_flight_path` only accepts paths whose base is `FlightPathBase::StagedPath`; it backs move and remove steps as well as non-contextual source resolution. A path carrying `AppDir`, `HomebrewPrefix` or `Literal` is rejected here: those bases are only translated by `resolve_flight_path_with_context` for the artifact types that support them.

Source

Thrown at src/system/packages/brew/cask.rs:3964

                );
            }
            matches.push(path);
        }
    }
    matches.sort();
    matches.dedup();
    Ok(matches)
}

fn is_flight_glob(path: &str) -> bool {
    path.chars()
        .any(|c| matches!(c, '*' | '?' | '[' | ']' | '{' | '}'))
}

fn resolve_flight_path(staged_path: &Path, path: &FlightPath) -> Result<PathBuf> {
    match path.base {
        FlightPathBase::StagedPath => {}
        _ => bail!("brew-cask: structured file operation must use staged_path"),
    }
    let relative = Path::new(&path.path);
    validate_flight_relative_path(&path.path)?;
    Ok(staged_path.join(relative))
}

fn resolve_flight_path_with_context(
    cask: &Cask,
    path: &FlightPath,
    staged_path: &Path,
    appdir: &Path,
) -> Result<PathBuf> {
    let expanded = expand_flight_template(cask, &path.path, staged_path, appdir);
    match path.base {
        FlightPathBase::StagedPath => {
            validate_flight_relative_path(&expanded)?;
            Ok(staged_path.join(expanded))
        }

View on GitHub (pinned to 6f52dcdf99)

Solutions

Express move and remove paths relative to the staged payload
Use artifact types that support contextual bases (copy or symlink) for appdir/prefix locations
Fix the base tag when constructing FlightPath values in code

Example fix

# before
move(source: "#{appdir}/Old.app", target: "#{staged}/Old.app")
# after - move only operates inside the staged payload
remove(path: "Old.app")

Defensive patterns

Strategy: type-guard

Type guard

// Only staged-based paths may go through strict move/remove resolution
fn is_staged_based(path: &FlightPath) -> bool {
    matches!(path.base, FlightPathBase::StagedPath)
}

Try / catch

if err.to_string().contains("must use staged_path") {
    // re-express the path relative to the staged payload or switch artifact type
}

Prevention

Keep move/remove steps staged-relative by construction
Route appdir/prefix locations through copy or symlink artifacts, which accept context bases
Unit-test FlightPath construction so the base is never guessed

When it happens

Trigger: A move or remove step whose FlightPath was built with base AppDir, HomebrewPrefix or Literal; remove-step paths templated from `#{appdir}` or absolute prefixes.

Common situations: Ported Homebrew ruby stanzas that use absolute or appdir paths in move/remove positions; programmatic FlightPath construction defaulting to the wrong base.

Related errors

AI-assisted analysis of jdx/mise@6f52dcdf99 (2026-08-22). Data as JSON: /api/errors/1342dc6c180299b8. Report an issue: GitHub.