From e00be74c8b575c725829677aadeb755ee81454d0 Mon Sep 17 00:00:00 2001 From: soryu Date: Fri, 8 May 2026 11:29:56 +0100 Subject: feat(directives): unified contracts surface — backbone (#128) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the backbone PR for the unified directive workflow. A directive holds a sequence of contracts; each contract is a spec body whose execution drives tasks in the directive's shared worktree. Lifecycle (Lock & Start, queue scheduler, drag-reorder) lands in follow-ups. What's in this PR: - Migration adds `position` (queue order) and `merge_mode` (shared|own_pr) columns to directive_documents. The actual table rename is deferred — the legacy `contracts` table from the old contracts system still exists, and the rename collision waits for Phase 5 to drop legacy contracts. - Repository: list orders by position; create assigns next-position; update accepts merge_mode; new reorder_directive_document_position shifts siblings inside a transaction. - HTTP: endpoints aliased under /api/v1/directives/{id}/contracts and /api/v1/contracts/{id}/... with a new /contracts/{id}/reorder. - Frontend: api types renamed `DirectiveContract*` (avoiding the legacy `Contract` type collision); document-directives.tsx imports via aliases so the rest of the file is untouched. Internal struct + table names stay `DirectiveDocument` / `directive_documents` until the legacy contracts cleanup. Co-authored-by: Claude Opus 4.7 (1M context) --- makima/frontend/src/lib/api.ts | 127 ++++++++++++--------- makima/frontend/src/routes/document-directives.tsx | 56 ++++----- 2 files changed, 104 insertions(+), 79 deletions(-) (limited to 'makima/frontend/src') diff --git a/makima/frontend/src/lib/api.ts b/makima/frontend/src/lib/api.ts index 80da511..17cf1d0 100644 --- a/makima/frontend/src/lib/api.ts +++ b/makima/frontend/src/lib/api.ts @@ -3583,116 +3583,141 @@ export async function pickUpOrders(directiveId: string): Promise { - const res = await authFetch(`${API_BASE}/api/v1/directives/${directiveId}/documents`); - if (!res.ok) throw new Error(`Failed to list directive documents: ${res.statusText}`); +export async function listDirectiveContracts( + directiveId: string, +): Promise { + const res = await authFetch(`${API_BASE}/api/v1/directives/${directiveId}/contracts`); + if (!res.ok) throw new Error(`Failed to list contracts: ${res.statusText}`); return res.json(); } -export async function createDirectiveDocument( +export async function createDirectiveContract( directiveId: string, - req: CreateDirectiveDocumentRequest = {}, -): Promise { - const res = await authFetch(`${API_BASE}/api/v1/directives/${directiveId}/documents`, { + req: CreateDirectiveContractRequest = {}, +): Promise { + const res = await authFetch(`${API_BASE}/api/v1/directives/${directiveId}/contracts`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(req), }); - if (!res.ok) throw new Error(`Failed to create directive document: ${res.statusText}`); + if (!res.ok) throw new Error(`Failed to create contract: ${res.statusText}`); return res.json(); } -export async function getDirectiveDocument(documentId: string): Promise { - const res = await authFetch(`${API_BASE}/api/v1/directive-documents/${documentId}`); - if (!res.ok) throw new Error(`Failed to get directive document: ${res.statusText}`); +export async function getDirectiveContract(contractId: string): Promise { + const res = await authFetch(`${API_BASE}/api/v1/contracts/${contractId}`); + if (!res.ok) throw new Error(`Failed to get contract: ${res.statusText}`); return res.json(); } /** - * Update a directive document's title and/or body. The backend auto-reactivates - * a shipped document when its body changes (re-stamps status to `active`), - * which is why we don't expose a separate "reactivate" call. + * Update a contract's title, body, and/or merge mode. Backend auto- + * reactivates a shipped contract when its body changes (status flips + * back to `active`), so there's no separate reactivate call. */ -export async function updateDirectiveDocument( - documentId: string, - req: UpdateDirectiveDocumentRequest, -): Promise { - const res = await authFetch(`${API_BASE}/api/v1/directive-documents/${documentId}`, { +export async function updateDirectiveContract( + contractId: string, + req: UpdateDirectiveContractRequest, +): Promise { + const res = await authFetch(`${API_BASE}/api/v1/contracts/${contractId}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(req), }); - if (!res.ok) throw new Error(`Failed to update directive document: ${res.statusText}`); + if (!res.ok) throw new Error(`Failed to update contract: ${res.statusText}`); + return res.json(); +} + +export async function archiveDirectiveContract(contractId: string): Promise { + const res = await authFetch(`${API_BASE}/api/v1/contracts/${contractId}/archive`, { + method: "POST", + }); + if (!res.ok) throw new Error(`Failed to archive contract: ${res.statusText}`); return res.json(); } -export async function archiveDirectiveDocument(documentId: string): Promise { - const res = await authFetch(`${API_BASE}/api/v1/directive-documents/${documentId}/archive`, { +/** Move a contract to a new 0-indexed queue position inside its directive. */ +export async function reorderDirectiveContract( + contractId: string, + position: number, +): Promise { + const res = await authFetch(`${API_BASE}/api/v1/contracts/${contractId}/reorder`, { method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ position }), }); - if (!res.ok) throw new Error(`Failed to archive directive document: ${res.statusText}`); + if (!res.ok) throw new Error(`Failed to reorder contract: ${res.statusText}`); return res.json(); } -/** Steps and tasks attached to a single directive document. Drives the - * per-document `tasks/` subfolder in the sidebar — when the document - * ships, its tasks visually move with it under shipped/. */ -export interface DocumentTasksResponse { +/** Steps and tasks attached to a single contract. Drives the per-contract + * `tasks/` subfolder in the sidebar — when the contract ships, its + * tasks visually move with it. */ +export interface DirectiveContractTasksResponse { steps: DirectiveStep[]; tasks: Task[]; } /** - * List the steps and ephemeral tasks attached to a specific directive - * document. Used by the sidebar to render a `tasks/` subfolder beside each - * document — including shipped documents, whose tasks remain attached so - * they continue to render under shipped/ alongside the document. + * List the steps and ephemeral tasks attached to a specific contract. + * Used by the sidebar to render a `tasks/` subfolder beside each + * contract — including shipped ones, whose tasks remain attached. */ -export async function listDirectiveDocumentTasks( - documentId: string, -): Promise { - const res = await authFetch( - `${API_BASE}/api/v1/directive-documents/${documentId}/tasks`, - ); - if (!res.ok) { - throw new Error(`Failed to list directive document tasks: ${res.statusText}`); - } +export async function listDirectiveContractTasks( + contractId: string, +): Promise { + const res = await authFetch(`${API_BASE}/api/v1/contracts/${contractId}/tasks`); + if (!res.ok) throw new Error(`Failed to list contract tasks: ${res.statusText}`); return res.json(); } diff --git a/makima/frontend/src/routes/document-directives.tsx b/makima/frontend/src/routes/document-directives.tsx index 1714aed..d589dac 100644 --- a/makima/frontend/src/routes/document-directives.tsx +++ b/makima/frontend/src/routes/document-directives.tsx @@ -7,16 +7,16 @@ import { DocumentEditor } from "../components/directives/DocumentEditor"; import { type DirectiveSummary, type DirectiveStatus, - type DirectiveDocument, - type DirectiveDocumentStatus, + type DirectiveContract as Contract, + type DirectiveContractStatus as ContractStatus, type DirectiveStep, type Task, - type DocumentTasksResponse, - listDirectiveDocuments, - createDirectiveDocument, - getDirectiveDocument, - updateDirectiveDocument, - listDirectiveDocumentTasks, + type DirectiveContractTasksResponse as ContractTasksResponse, + listDirectiveContracts as listContracts, + createDirectiveContract as createContract, + getDirectiveContract as getContract, + updateDirectiveContract as updateContract, + listDirectiveContractTasks as listContractTasks, createDirectiveTask, startDirective, pauseDirective, @@ -43,7 +43,7 @@ const STATUS_DOT: Record = { // Per-document status palette. Active/draft documents use the same bright // green-ish accent as a running directive; shipped/archived use a muted blue. -const DOC_STATUS_DOT: Record = { +const DOC_STATUS_DOT: Record = { draft: "bg-[#556677]", active: "bg-green-400", shipped: "bg-[#75aafc]", @@ -66,7 +66,7 @@ const DOC_STATUS_DOT: Record = { // rather than just an id slice). Accepts either a DirectiveSummary or a full // DirectiveWithSteps — only `title` is read. function fileLabel( - doc: DirectiveDocument, + doc: Contract, directive: { title: string }, ): string { const docTitle = doc.title.trim(); @@ -172,7 +172,7 @@ interface DirectiveFolderProps { /** Called when the user clicks the folder header itself (after toggle). */ onHeaderClick: () => void; selection: SidebarSelection | null; - onSelectDocument: (directiveId: string, doc: DirectiveDocument) => void; + onSelectDocument: (directiveId: string, doc: Contract) => void; onCreateDocument: (directive: DirectiveSummary) => Promise; /** Open the inline "+ New ephemeral task" form for this directive. */ onCreateEphemeralTask: (directive: DirectiveSummary) => void; @@ -210,7 +210,7 @@ function DirectiveFolder({ // Documents fetched lazily on open. We deliberately scope the fetch to the // open-state so closed folders don't pay the network cost on initial render. - const [docs, setDocs] = useState(null); + const [docs, setDocs] = useState(null); const [docsLoading, setDocsLoading] = useState(false); const [docsError, setDocsError] = useState(null); @@ -224,7 +224,7 @@ function DirectiveFolder({ setDocsLoading(true); setDocsError(null); try { - const list = await listDirectiveDocuments(directive.id); + const list = await listContracts(directive.id); setDocs(list); } catch (e) { setDocsError(e instanceof Error ? e.message : "Failed to load documents"); @@ -242,8 +242,8 @@ function DirectiveFolder({ // Split the documents into the two visual groups. Memoised so we don't // recompute on every render. const { activeDocs, shippedDocs } = useMemo(() => { - const active: DirectiveDocument[] = []; - const shipped: DirectiveDocument[] = []; + const active: Contract[] = []; + const shipped: Contract[] = []; for (const d of docs ?? []) { if (d.status === "shipped" || d.status === "archived") { shipped.push(d); @@ -447,7 +447,7 @@ function DirectiveFolder({ // ============================================================================= interface DocumentRowProps { - doc: DirectiveDocument; + doc: Contract; directive: DirectiveSummary; selected: boolean; onSelect: () => void; @@ -547,7 +547,7 @@ function DocumentTasksFolder({ onSelectTask, }: DocumentTasksFolderProps) { const [open, setOpen] = useState(defaultOpen); - const [data, setData] = useState(null); + const [data, setData] = useState(null); const [loading, setLoading] = useState(false); const [error, setError] = useState(null); @@ -561,7 +561,7 @@ function DocumentTasksFolder({ setLoading(true); setError(null); try { - const res = await listDirectiveDocumentTasks(documentId); + const res = await listContractTasks(documentId); setData(res); } catch (e) { setError(e instanceof Error ? e.message : "Failed to load tasks"); @@ -770,7 +770,7 @@ interface SidebarProps { directives: DirectiveSummary[]; loading: boolean; selection: SidebarSelection | null; - onSelectDocument: (directiveId: string, doc: DirectiveDocument) => void; + onSelectDocument: (directiveId: string, doc: Contract) => void; onSelectDirective: (directiveId: string) => void; onCreateDocument: (directive: DirectiveSummary) => Promise; onCreateContract: () => void; @@ -894,8 +894,8 @@ function DocumentSidebar({ // ============================================================================= // Editor shell — wraps DocumentEditor and handles the "no document selected" // and loading states. Two modes: -// 1) documentId selected → fetch the DirectiveDocument and edit doc.body via -// updateDirectiveDocument (the call that auto-reactivates a shipped doc). +// 1) documentId selected → fetch the Contract and edit doc.body via +// updateContract (the call that auto-reactivates a shipped doc). // 2) no documentId (legacy fallback, kept for the "select a directive but // not a document" transitional case) → edit directive.goal as before. // ============================================================================= @@ -918,7 +918,7 @@ function EditorShell({ const documentId = selection?.documentId ?? null; // We deliberately don't pull `updateGoal` here — in the multi-document - // world, edits flow through updateDirectiveDocument (which auto-reactivates + // world, edits flow through updateContract (which auto-reactivates // a shipped doc when its body changes). The legacy directive.goal is // unused on this surface. const { @@ -932,7 +932,7 @@ function EditorShell({ // Document fetch — only when documentId is selected. Refetched whenever the // id changes; not polled (the document stream is too low-traffic to warrant // background refresh in this iteration). - const [doc, setDoc] = useState(null); + const [doc, setDoc] = useState(null); const [docLoading, setDocLoading] = useState(false); const [docError, setDocError] = useState(null); @@ -946,7 +946,7 @@ function EditorShell({ let cancelled = false; setDocLoading(true); setDocError(null); - getDirectiveDocument(documentId) + getContract(documentId) .then((d) => { if (cancelled) return; setDoc(d); @@ -970,7 +970,7 @@ function EditorShell({ const onUpdateDocumentBody = useCallback( async (body: string) => { if (!documentId) return; - const updated = await updateDirectiveDocument(documentId, { body }); + const updated = await updateContract(documentId, { body }); setDoc(updated); // Tell the sidebar to refetch the directive's document list so the // status chip flips from `shipped` back to `active` (and any title @@ -1230,7 +1230,7 @@ export default function DocumentDirectivesPage() { lastResolvedRef.current = routeDirectiveId; let cancelled = false; - listDirectiveDocuments(routeDirectiveId) + listContracts(routeDirectiveId) .then((list) => { if (cancelled) return; // Prefer the first 'active' doc; fall back to the first 'draft'. @@ -1259,7 +1259,7 @@ export default function DocumentDirectivesPage() { }, [routeDirectiveId, selection?.documentId, selection?.taskId, setSearchParams]); const handleSelectDocument = useCallback( - (directiveId: string, doc: DirectiveDocument) => { + (directiveId: string, doc: Contract) => { navigate(`/directives/${directiveId}?document=${doc.id}`); }, [navigate], @@ -1278,7 +1278,7 @@ export default function DocumentDirectivesPage() { const handleCreateDocument = useCallback( async (directive: DirectiveSummary) => { - const created = await createDirectiveDocument(directive.id, { + const created = await createContract(directive.id, { title: "", body: "", }); -- cgit v1.2.3