Api Laravel Package

Technical Evaluation

Architecture fit

• The package is a Laravel-side client for the Cipi server control API; 1.35.0 extends it from app/deploy lifecycle management into declarative server configuration (cipi.yml) — plan, apply, and auto-apply. This is a meaningful scope expansion: the package now sits on the path that can mutate production server config, not just read state or trigger deploys.
• Fits the existing package shape cleanly: new routes map to controller actions, yml-view/yml-manage map to the existing token-ability authorization model, and POST /yml/apply reuses the established async-job pattern (app-yml-apply).
• Read/write split is well designed for a TPM-facing surface: GET /yml is synchronous and read-only (safe to poll, safe to surface in dashboards), apply is async, auto/enable|disable is synchronous and idempotent (safe to retry).
• MCP parity (AppYmlShow, AppYmlApply, AppYmlAuto) means the same capabilities are reachable from agent/tooling surfaces — relevant if we intend to expose server config operations to AI-assisted workflows.

Integration feasibility

• Straightforward to consume: OpenAPI info.version bumps to 1.35.0 with 4 new paths under a cipi.yml tag plus typed schemas (YmlPlanResponse, YmlAutoResponse, JobResultAppYmlApply). Client stubs/codegen can be regenerated.
• Hard prerequisite: Cipi CLI ≥ 5.6.4 on every target server (cipi self-update, migration 5.6.4). This is the gating item for the whole feature set, not a per-endpoint detail.
• Token migration required: yml-view and yml-manage are not granted to existing tokens. Any pre-existing integration token will 403 on the new routes until a new token is minted via cipi api token create. This is a clean cutover but an unavoidable coordination step.
• Server-side sudoers changes (/etc/sudoers.d/cipi-api gaining cipi yml plan *, apply *, auto *) are applied by the 5.6.4 migration — worth verifying rather than assuming, since a partially-migrated host is the most likely source of hard-to-diagnose failures.

Technical risk

• Version-skew is the dominant risk. Mixed-fleet servers on older Cipi return 503 for the new endpoints while all other routes behave as 1.34.0. Any UI or automation must treat 503 on these paths as "capability unavailable," not transient failure — otherwise retry logic will hammer a permanently-unavailable endpoint.
• Ambiguous job failure semantics. apply returns outcome of applied, unchanged, partial, blocked, invalid, or no-file; the last four terminate the job as failed while still carrying a result payload. Consumers that key off job status alone will discard the diagnostic detail (failures, blockers, errors) needed to explain what happened. This must be encoded in the client, not left to individual call sites.
• Auto-apply is a privilege-equivalent change. With auto-apply on, anyone who can commit to the repository controls that app's server configuration. The release notes explicitly recommend client-side confirmation; that's a product control we must implement, not assume the API enforces.
• app-yml-apply is asynchronous, so any synchronous "apply and show me" UX needs a job-polling layer with timeout and terminal-state handling.
• Minor but real: the job-result change (falling back to the job's parameters for an app key the CLI text couldn't supply) alters output shape in some cases — low impact, but it's a behavioral change in a shared result path.

Key questions

1. What is the current Cipi CLI version distribution across our fleet, and who owns the 5.6.4 rollout?
2. Do we have a documented token rotation path, and is a dual-token window (old for 1.34.0 routes, new for yml-*) acceptable, or do we force a single cutover?
3. Who is authorized to enable auto-apply, and what approval gate do we require before the UI/API call?
4. Do we consume the OpenAPI spec for codegen? If so, when does the 1.35.0 spec get pulled into our pipeline?
5. Is the MCP tool surface (AppYmlApply in particular) exposed to any agent with unattended execution rights? If yes, that needs a separate review.
6. How do we want to present blockers and valid.errors/warnings — pre-apply gate in the UI, or post-hoc reporting?

Integration Approach

Stack fit

• Laravel-native consumption: package config (config/cipi.php) for abilities, existing job/polling conventions for app-yml-apply, existing HTTP client for the new routes. No new infrastructure class required.
• The natural product surfaces are (a) a read-only config view backed by GET /yml showing in_sync, changes, blockers, valid; (b) a gated apply action; (c) an auto-apply toggle with a confirmation step.
• GET /yml being synchronous and read-only makes it safe to render directly in an admin panel without a queue hop — a genuine simplification versus the deploy endpoints.

Migration path

1. Server-side first: roll Cipi to 5.6.4 across the fleet; verify /etc/sudoers.d/cipi-api reflects the three new cipi yml permissions per host; confirm cipi yml plan --json works locally on a representative host.
2. Token second: mint tokens carrying yml-view (read-only consumers) and yml-manage (write consumers) separately — don't bundle manage into tokens that only need to display state.
3. Package third: bump to 1.35.0, regenerate from the 1.35.0 OpenAPI spec, and add explicit 503 handling on the four new paths.
4. Feature last: ship read-only plan view to all users; gate apply behind yml-manage; gate auto-apply behind an additional confirmation flow.

Compatibility

• Backward compatible at the package level: "every other route is as in 1.34.0." No deprecations announced.
• Forward compatibility is conditional on server version — this is a server-gated feature, so the package version alone does not tell you whether a capability is available. Surface that distinction in our own capability detection rather than in the package version.
• OpenAPI info.version is now 1.35.0; if we pin generated clients to spec versions, expect a diff limited to the new tag/paths/schemas plus the job-type enum addition.

Sequencing

• Phase 1 — Read-only observability (yml-view): plan view, in-sync/blockers/warnings. Low risk, immediate operator value, no server mutation.
• Phase 2 — Manual apply (yml-manage): explicit user action, full result rendering across all six outcome values, job polling with terminal-state handling for the four failure outcomes.
• Phase 3 — Auto-apply: requires the confirmation control, an authorization decision, and audit logging before enablement. Treat as a separate release with its own review.
• MCP exposure should trail the HTTP surface by one phase, and AppYmlApply/AppYmlAuto via MCP should require the same authorization gate as the HTTP route.

Operational Impact

Maintenance

• Two version surfaces to track: the package (1.35.0) and the Cipi CLI floor (5.6.4). Document both in the runbook; a package bump alone will not deliver the feature.
• OpenAPI spec regeneration becomes a recurring chore; add it to the release checklist so client drift is caught at upgrade time.
• cipi.yml becomes a configuration artifact we now own operationally — schema changes in future Cipi releases will surface as new errors/warnings in yml plan, which is a reasonable early-warning mechanism but also a new class of alert to triage.

Support

• First-line support needs a decision tree keyed on outcome: invalid (fix the file), blocked (resolve listed blockers), partial (inspect failures/failed), no-file (nothing to apply), unchanged (no-op, not an error), applied (success). Four of these arrive as failed jobs — support scripts must read the result payload, not the job status.
• 503 on yml-* routes should route to "server needs Cipi 5.6.4," not to generic API-outage handling.
• 403 on yml-* routes should route to "token lacks yml-view/yml-manage," which is the expected state for every pre-existing token.

Scaling

• GET /yml is synchronous; it shells out to cipi yml plan --json per request. If it's used in a list view across many apps, that's N subprocess invocations — plan for caching or on-demand fetch rather than eager per-row loading.
• apply is async and bounded by the job system; concurrency limits should be set conservatively since applies mutate server state and a blocked/partial outcome may leave a host mid-change.
• MCP at 76 tools on a single tools/list page is fine today; note the ceiling as the tool count grows.

Failure modes

Ramp-up

• Engineering: low — new routes onto existing patterns; main effort is the outcome-state machine and 503/403 discrimination.
• Ops/SRE: moderate — fleet CLI upgrade, sudoers verification, token re-issuance, and a new alert class around config drift.
• End users: moderate for apply (six outcomes to understand), high-caution for auto-apply (conceptually simple toggle, significant blast radius). Auto-apply should ship with explicit copy stating that repo commit access becomes server config access.
• Recommend a single pilot app for Phase 1–2 before broadening; auto-apply pilot on a non-critical app only after audit logging exists.