Skip to content
Browse documentation
guides

CI and troubleshooting

Automate explicit native checks, interpret structured outcomes, and diagnose failures at the boundary that owns them.

Verify retained inputs in CI

Provision the reviewed CLI, native tools, private application source, retained vendor artifacts, and required services explicitly. Normal application CI does not need private Framework acquisition when those artifacts are already present. Public third-party dependencies and browser assets may still require network access. Do not silently select a newer Framework release as part of installing the app.

bash
bun install --frozen-lockfile --ignore-scripts
smoothie project check --format json
smoothie project verify --format json
smoothie project verify --task typecheck --task test --task build --run --format json

Use a lockfile generated and reviewed for the current dependencies. Configure explicit browser/service jobs when required. Native checks run on supported macOS/Linux hosts; a Windows executable is not support for Windows native task execution. Project scripts are your application's code: the CLI runs them without a sandbox, and a passing script can still skip tests internally.

Consume structured results without broadening authority

One-shot JSON stdout contains a versioned result; native progress uses stderr. Check status, diagnostics, effects, and per-check outcomes. Treat missing or malformed output as failure. Exit codes are 0 for requested success, 2 for invalid arguments, 3 for blocked prerequisites, 4 for failed checks/effects, and 130 for cancellation. Native exit codes remain in check records; a suggested next action is not permission to execute it.

Separate acquisition credentials, provider test credentials, and deployment authority. A retained read, a passing check, or an MCP connection must not grant uploads. Redact logs before sharing them; trusted scripts can print secrets even when the CLI does not inspect or include environment values in its own metadata output.

Investigate the owning boundary

Private acquisition deniedCheck the separately authenticated gh account and entitled repository access. Do not replace paid artifacts with historical public packages.
Verification or retained archive failureRestore a complete matching source/bundle or retained selection. Do not edit inventory hashes to accept changed files.
Project metadata blockedInspect the reported manifest and field. Malformed ancestor metadata is not bypassed by searching for a different project.
Frozen lockfile or install failureCheck the current package references and native lock diff. Regenerate only for an intentional reviewed dependency change; review required install hooks separately.
Task unavailable or tests skippedDeclare and review the intended native script. Supply real service prerequisites; exit zero or an empty task is not missing coverage.
Expected plan changedReinspect changed inputs, request a new plan, and review it. Do not blindly replace approval hashes.
Deployment unknownKeep the attempt and query provider state before another upload. Submission, traffic observation, and application health are different facts.
Custom package rejectedVerify replacement versions, archive hashes, license identity and the complete dependency/peer closure against the custom-build contract.

Leave a useful handoff

Record the CLI version, retained Framework identity, selected tasks, actual outcomes, configured service lane, and remaining limitations. Share only reviewed, redacted evidence. For interrupted package writes, follow recovery; for remote operations, follow deployment reconciliation. Neither a command plan nor a user's request to investigate is authority to retry a deployment or discard application data.