From fe6b78fa59657449be2e888402e3a0197b5c0621 Mon Sep 17 00:00:00 2001 From: soryu Date: Thu, 30 Apr 2026 17:08:30 +0100 Subject: feat(directives): per-PR revision snapshots + sidebar history (#112) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stage 3 of the doc-mode revamp. Builds the foundation for treating contracts as living specifications by freezing their content into a revision every time a PR is raised. ## directive_revisions table (new migration) (id, directive_id, content, pr_url, pr_branch, pr_state, version, frozen_at) with UNIQUE(directive_id, version) and a partial index on pr_state='open' so the next reconciler iteration can poll only what's still in flight. pr_state is constrained to 'open' | 'merged' | 'closed' to mirror GitHub's PR lifecycle. For Stage 3 we only freeze on PR creation; pr_state poll is deferred to a follow-up. ## Repository helpers - create_directive_revision: idempotent on (directive_id, pr_url) so a re-run of the orchestrator's completion task can't double-snapshot. Auto-assigns version = MAX(existing) + 1 per directive. - list_directive_revisions_for_owner: scoped through the directive join so users can only read their own contract history. - update_directive_revision_pr_state: stub for the upcoming poller. - get_latest_merged_revision: returns the most recent merged revision — this is what Stage 4 will diff against on amendments. ## Snapshot trigger update_directive handler now reads the BEFORE pr_url before the update. If pr_url transitions None → Some, it snapshots the directive's current goal as a revision tied to the new pr_url. Failures log and continue — the directive update itself is unaffected. ## API + OpenAPI GET /api/v1/directives/{id}/revisions returns DirectiveRevisionListResponse (revisions newest-first). Schemas registered in OpenAPI. ## Frontend: revisions/ subfolder + read-only viewer Each contract folder now has a third subfolder ("revisions/") that lazily fetches and lists past revisions when the parent directive folder is open. Empty contracts skip the subfolder entirely so brand-new ones aren't cluttered. Each row shows v.md plus a small pill ('open'/'merged'/ 'closed'). Selecting a revision encodes itself into the existing ?task= param as "revision:", so EditorShell can route between the live task stream (realTaskId), the read-only RevisionViewer (revisionId), or the editor itself (neither). The viewer renders the frozen markdown verbatim with a deep-link to the PR — these are immutable historical records, not edit surfaces. Co-authored-by: Claude Opus 4.7 (1M context) --- makima/src/server/handlers/directives.rs | 100 ++++++++++++++++++++++++++++++- 1 file changed, 98 insertions(+), 2 deletions(-) (limited to 'makima/src/server/handlers') diff --git a/makima/src/server/handlers/directives.rs b/makima/src/server/handlers/directives.rs index 44bf4ac..91f5892 100644 --- a/makima/src/server/handlers/directives.rs +++ b/makima/src/server/handlers/directives.rs @@ -11,12 +11,14 @@ use uuid::Uuid; use crate::db::models::{ CleanupResponse, CreateDirectiveRequest, CreateTaskRequest, CreateDirectiveStepRequest, Directive, DirectiveListResponse, - DirectiveStep, DirectiveWithSteps, PickUpOrdersResponse, + DirectiveRevision, DirectiveStep, DirectiveWithSteps, PickUpOrdersResponse, UpdateDirectiveRequest, UpdateDirectiveStepRequest, UpdateGoalRequest, CreateDirectiveOrderGroupRequest, DirectiveOrderGroup, DirectiveOrderGroupListResponse, UpdateDirectiveOrderGroupRequest, OrderListResponse, }; +use serde::Serialize; +use utoipa::ToSchema; use crate::db::repository; use crate::orchestration::directive::{ build_cleanup_prompt, build_order_pickup_prompt, classify_goal_change, @@ -185,8 +187,50 @@ pub async fn update_directive( .into_response(); }; + // Capture the BEFORE state so we can detect a pr_url transition (null + // → some-value), which is when the orchestrator's completion task has + // raised a PR for this directive. That transition is the trigger for + // freezing a directive_revisions snapshot. + let before_pr_url = match repository::get_directive_for_owner(pool, auth.owner_id, id).await { + Ok(Some(d)) => d.pr_url.clone(), + _ => None, + }; + match repository::update_directive_for_owner(pool, auth.owner_id, id, req).await { - Ok(Some(directive)) => Json(directive).into_response(), + Ok(Some(directive)) => { + // Detect "PR was just raised" — pr_url went from None to Some. + // Snapshot the current goal as a revision tied to this PR. + // Best-effort: a snapshot failure should not fail the update, + // because the directive's pr_url has already been written. + if before_pr_url.is_none() { + if let Some(ref new_pr_url) = directive.pr_url { + if let Err(e) = repository::create_directive_revision( + pool, + directive.id, + &directive.goal, + new_pr_url, + directive.pr_branch.as_deref(), + ) + .await + { + tracing::warn!( + directive_id = %directive.id, + pr_url = %new_pr_url, + error = %e, + "Failed to snapshot directive revision on PR creation — \ + continuing; revision history will be incomplete" + ); + } else { + tracing::info!( + directive_id = %directive.id, + pr_url = %new_pr_url, + "Snapshotted directive revision on PR creation" + ); + } + } + } + Json(directive).into_response() + } Ok(None) => ( StatusCode::NOT_FOUND, Json(ApiError::new("NOT_FOUND", "Directive not found")), @@ -2038,3 +2082,55 @@ pub async fn pick_up_dog_orders( }) .into_response() } + +// ============================================================================= +// Directive Revisions (per-PR snapshots) +// ============================================================================= + +#[derive(Debug, Serialize, ToSchema)] +#[serde(rename_all = "camelCase")] +pub struct DirectiveRevisionListResponse { + pub revisions: Vec, + pub total: i64, +} + +/// List all per-PR revisions for a directive, newest first. +#[utoipa::path( + get, + path = "/api/v1/directives/{id}/revisions", + params(("id" = Uuid, Path, description = "Directive ID")), + responses( + (status = 200, description = "Revision history", body = DirectiveRevisionListResponse), + (status = 503, description = "Database not configured", body = ApiError), + ), + security(("bearer_auth" = []), ("api_key" = [])), + tag = "Directives" +)] +pub async fn list_directive_revisions( + State(state): State, + Authenticated(auth): Authenticated, + Path(id): Path, +) -> impl IntoResponse { + let Some(ref pool) = state.db_pool else { + return ( + StatusCode::SERVICE_UNAVAILABLE, + Json(ApiError::new("DB_UNAVAILABLE", "Database not configured")), + ) + .into_response(); + }; + + match repository::list_directive_revisions_for_owner(pool, auth.owner_id, id).await { + Ok(revisions) => { + let total = revisions.len() as i64; + Json(DirectiveRevisionListResponse { revisions, total }).into_response() + } + Err(e) => { + tracing::error!("Failed to list directive revisions: {}", e); + ( + StatusCode::INTERNAL_SERVER_ERROR, + Json(ApiError::new("LIST_FAILED", &e.to_string())), + ) + .into_response() + } + } +} -- cgit v1.2.3